# GCP Admin Skill

Manage Google Cloud Platform resources using the `aria-firebase-admin` service account. This skill covers infrastructure operations, API management, OAuth clients, Firebase, and common troubleshooting.

## Core Principle

**Nothing is off-limits by default.** The service account has broad access. When you hit "permission denied" or "API not enabled" errors:

1. **Try enabling the API first** — most APIs are just disabled, not inaccessible
2. **Check IAM roles** — the SA has Editor + Firebase Admin on most Symph projects
3. **Don't assume unavailable** — if Raven says "you have access," dig deeper

## Service Account

**Primary SA:** `aria-firebase-admin@the-agency-symph.iam.gserviceaccount.com`
**Key file:** `~/.config/gcloud/aria-firebase-admin.json`

### Permissions (as of 2026-02-19)

| Project | Roles |
|---------|-------|
| `the-agency-symph` | Editor, Firebase Admin, Service Account User |
| Symph Products folder (`436092539710`) | Project Creator |
| Individual `symph-*` projects | Varies (usually Editor) |

### Setup for Commands

Always set these before running gcloud/curl commands:

```bash
export PATH="/home/aria/google-cloud-sdk/bin:$PATH"
export GOOGLE_APPLICATION_CREDENTIALS="$HOME/.config/gcloud/aria-firebase-admin.json"
```

Get an access token for API calls:
```bash
TOKEN=$(gcloud auth application-default print-access-token)
```

## Enabling APIs

**Key lesson:** Most "permission denied" errors are actually "API not enabled" errors in disguise. Always try enabling the API first.

```bash
# Enable an API
gcloud services enable SERVICE_NAME --project=PROJECT_ID

# List enabled APIs
gcloud services list --project=PROJECT_ID

# Common APIs and what they do:
# - iap.googleapis.com          → Identity-Aware Proxy, OAuth client creation
# - firebase.googleapis.com     → Firebase management
# - firestore.googleapis.com    → Firestore database
# - cloudbuild.googleapis.com   → Cloud Build
# - run.googleapis.com          → Cloud Run
# - cloudresourcemanager.googleapis.com → Project/folder management
# - serviceusage.googleapis.com → API management itself
```

## OAuth Client Management (IAP API)

This was a hard-won lesson: OAuth 2.0 clients CAN be created programmatically via the IAP API, even though the regular Console-created clients can't be modified via API.

### Enable IAP API
```bash
gcloud services enable iap.googleapis.com --project=PROJECT_ID
```

### List OAuth Brands
```bash
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://iap.googleapis.com/v1/projects/PROJECT_NUM/brands" | jq '.'
```

### Create OAuth Client
```bash
PROJECT_NUM="1074779943765"  # Get from: gcloud projects describe PROJECT_ID --format='value(projectNumber)'

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"displayName": "My App Name"}' \
  "https://iap.googleapis.com/v1/projects/$PROJECT_NUM/brands/$PROJECT_NUM/identityAwareProxyClients"
```

Response includes `name` (with client ID) and `secret`.

### List OAuth Clients
```bash
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://iap.googleapis.com/v1/projects/$PROJECT_NUM/brands/$PROJECT_NUM/identityAwareProxyClients" | jq '.'
```

### Delete OAuth Client
```bash
CLIENT_ID="1074779943765-xxxxx.apps.googleusercontent.com"
curl -X DELETE -H "Authorization: Bearer $TOKEN" \
  "https://iap.googleapis.com/v1/projects/$PROJECT_NUM/brands/$PROJECT_NUM/identityAwareProxyClients/$CLIENT_ID"
```

**Important limitation:** IAP-created OAuth clients are **only for IAP-protected GCP resources**. They do NOT support custom redirect URIs and cannot be used for generic OAuth flows (like NextAuth). For custom OAuth apps, you must still use the Console to create/configure clients with specific redirect URIs.

## Firebase Operations

### Create Firebase Project
```bash
# Create GCP project first (under Symph Products folder)
gcloud projects create symph-SLUG --display-name="Product Name" --folder=436092539710

# Enable Firebase
firebase projects:addfirebase symph-SLUG
```

### Deploy Firestore Rules
```bash
firebase deploy --only firestore:rules --project symph-SLUG
```

### Get Web App Config
```bash
firebase apps:sdkconfig WEB --project symph-SLUG
```

### Enable Firebase Services
```bash
gcloud services enable firebase.googleapis.com --project=symph-SLUG
gcloud services enable firestore.googleapis.com --project=symph-SLUG
gcloud services enable firebasestorage.googleapis.com --project=symph-SLUG
```

## Billing Management

### Link Billing Account
```bash
# Symph billing account
gcloud billing projects link PROJECT_ID --billing-account=01F3D7-6E8F01-1E2163
```

### Check Billing Status
```bash
gcloud billing projects describe PROJECT_ID
```

## Storage Operations

### Create Storage Bucket
```bash
gsutil mb -p PROJECT_ID -l us-central1 gs://BUCKET_NAME
```

### Make Bucket Public
```bash
gsutil iam ch allUsers:objectViewer gs://BUCKET_NAME
```

### Set CORS
```bash
cat > /tmp/cors.json << 'EOF'
[{"origin": ["*"], "method": ["GET"], "maxAgeSeconds": 3600}]
EOF
gsutil cors set /tmp/cors.json gs://BUCKET_NAME
```

## Cloud Run Deployments

### Deploy from Source
```bash
gcloud run deploy SERVICE_NAME \
  --source . \
  --region=us-central1 \
  --project=PROJECT_ID \
  --allow-unauthenticated
```

### Map Custom Domain
```bash
gcloud run domain-mappings create \
  --service=SERVICE_NAME \
  --domain=DOMAIN.com \
  --region=us-central1 \
  --project=PROJECT_ID
```

## IAM Management

### Check Project IAM
```bash
gcloud projects get-iam-policy PROJECT_ID --format=json | jq '.bindings[] | select(.members[] | contains("aria-firebase"))'
```

### Add IAM Binding
```bash
gcloud projects add-iam-policy-binding PROJECT_ID \
  --member="serviceAccount:SA_EMAIL" \
  --role="roles/ROLE_NAME"
```

## API Keys

### List API Keys
```bash
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://apikeys.googleapis.com/v2/projects/PROJECT_NUM/locations/global/keys" | jq '.'
```

### Create API Key
```bash
curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"displayName": "Key Name", "restrictions": {"apiTargets": [{"service": "SERVICE.googleapis.com"}]}}' \
  "https://apikeys.googleapis.com/v2/projects/PROJECT_NUM/locations/global/keys"
```

## Common Troubleshooting

### "Permission Denied"
1. Check if API is enabled: `gcloud services list --project=PROJECT_ID | grep SERVICE`
2. If not enabled: `gcloud services enable SERVICE.googleapis.com --project=PROJECT_ID`
3. Check IAM roles: `gcloud projects get-iam-policy PROJECT_ID`

### "API Not Enabled"
```bash
gcloud services enable SERVICE_NAME.googleapis.com --project=PROJECT_ID
```

### "Quota Exceeded"
Check quotas in Console or request increase. Some quotas can be adjusted via API:
```bash
gcloud alpha services quota update --service=SERVICE --consumer=PROJECT_ID --metric=METRIC --unit=UNIT --value=VALUE
```

### "Resource Not Found"
- Check project ID vs project number (some APIs need one or the other)
- Get project number: `gcloud projects describe PROJECT_ID --format='value(projectNumber)'`

## Project Structure

Symph projects follow this pattern:
- **Folder:** `436092539710` (Symph Products)
- **Project ID:** `symph-{slug}` (e.g., `symph-worklane`)
- **Billing:** `01F3D7-6E8F01-1E2163` (Symph billing)

## Quick Reference

| Task | Command |
|------|---------|
| Get access token | `gcloud auth application-default print-access-token` |
| List enabled APIs | `gcloud services list --project=PROJECT` |
| Enable API | `gcloud services enable API.googleapis.com --project=PROJECT` |
| Check IAM | `gcloud projects get-iam-policy PROJECT` |
| Project number | `gcloud projects describe PROJECT --format='value(projectNumber)'` |
| Create OAuth client | Use IAP API (see above) |
| Deploy Firestore rules | `firebase deploy --only firestore:rules --project=PROJECT` |

## Key APIs Reference

| API | What It Enables |
|-----|-----------------|
| `iap.googleapis.com` | OAuth client creation/management |
| `firebase.googleapis.com` | Firebase project operations |
| `firestore.googleapis.com` | Firestore database |
| `firebasestorage.googleapis.com` | Firebase Storage |
| `run.googleapis.com` | Cloud Run deployments |
| `cloudbuild.googleapis.com` | Cloud Build |
| `apikeys.googleapis.com` | API key management |
| `cloudresourcemanager.googleapis.com` | Project/folder management |
| `serviceusage.googleapis.com` | Enable/disable other APIs |
| `identitytoolkit.googleapis.com` | Firebase Auth config |

---

**Remember:** When in doubt, enable the API first. The service account has more access than you might think.
