GCP Specialist
Structured investigation for Google Cloud workloads. Five phases: gather context,
diagnose, design, recommend, verify.
Arguments
$0 — project context, service scope, or problem description. Required.
Phase 1: Context Gathering
- Identify the organization, folders, project(s), and services in scope.
- Glob for IaC in the working directory:
**/*.tf, **/*.yaml (Config Connector), **/*.jinja (Deployment Manager legacy).
- If gcloud CLI access is available:
gcloud config list
gcloud projects list
gcloud auth list
- List enabled APIs in the current project:
gcloud services list --enabled --format="value(config.name)"
Phase 2: Diagnosis
Compute / containers:
gcloud compute instances list
gcloud container clusters list
gcloud run services list
IAM / identity:
gcloud projects get-iam-policy <project>
gcloud iam service-accounts list
gcloud iam workload-identity-pools list --location=global
Networking:
gcloud compute networks list
gcloud compute firewall-rules list
gcloud compute routers list
Serverless / events:
gcloud functions list
gcloud pubsub topics list
gcloud pubsub subscriptions list
Cost / quotas:
gcloud compute project-info describe --format="yaml(quotas)"
gcloud logging read 'resource.type="gce_instance"' --limit=20 --format=json
Phase 3: Design / Root-Cause Analysis
Map symptoms to causes:
| Symptom |
Common Causes |
Check |
| GKE pod AuthN fails |
Workload Identity not bound, KSA/GSA annotation mismatch |
kubectl describe sa + gcloud iam service-accounts get-iam-policy |
| Cloud Run cold starts |
min-instances=0, cold container image |
gcloud run services describe → min-instances, image size |
| GCS AccessDenied |
Uniform vs fine-grained mismatch, missing roles/storage.objectViewer |
gsutil iam get + project-level IAM |
| Pub/Sub messages stuck |
Subscription ack deadline too short, consumer crashed |
gcloud pubsub subscriptions describe + dead-letter config |
| BigQuery slow query |
Missing clustering/partitioning, full table scan |
Query plan review, DRY_RUN pricing |
| VPC connectivity fail |
Firewall default-deny, missing Private Google Access |
gcloud compute firewall-rules list + subnet Private Google Access flag |
Cite resource self-link or file:line for every finding.
Phase 4: Recommendations
Output findings in priority order:
[CRITICAL] <title>
Resource: <self-link or file:line>
Issue: <one sentence>
Evidence: <gcloud output or code snippet>
Fix: <specific change, with Terraform/Config Connector diff>
Trade-off: <alternative and its downside, if meaningful>
- Order: CRITICAL → WARNING → INFO.
- For IaC fixes, show the exact Terraform or Config Connector diff.
- Reference relevant docs in
references/ where applicable.
Phase 5: Verification
After fixes are applied:
- Re-run the diagnostic command that surfaced the issue.
- For Workload Identity changes:
gcloud iam service-accounts get-iam-policy and live pod token request.
- For firewall changes:
gcloud compute firewall-rules list + connectivity probe.
- For IAM changes:
gcloud projects get-iam-policy --flatten="bindings[].members" to see effective membership.
- Check Cloud Monitoring dashboards and Error Reporting — no new incidents should be open.
Reference Docs
Consult references/ for decision guides:
| File |
When to use |
compute.md |
GKE, Cloud Run, GCE selection and sizing |
serverless.md |
Cloud Functions, Pub/Sub, Cloud Tasks, Eventarc |
storage.md |
GCS, Filestore, BigQuery, Cloud SQL, Spanner |
networking.md |
VPC, Cloud Load Balancing, Cloud Armor, Cloud CDN |
iam.md |
IAM hierarchy, Workload Identity, Service Accounts |
observability.md |
Cloud Monitoring, Logging, Trace, Error Reporting |
iac-patterns.md |
Terraform, Config Connector, Deployment Manager patterns |
1---2name: gcp-specialist3description: Deep-dive Google Cloud architecture review, debugging, and service design. Use for structured investigations of GCP-specific issues, IAM or cost audits, and multi-service design reviews. Triggers on: "GCP audit", "GCP design review", "Workload Identity debug", "IAM review GCP", "review my GKE", "GCP troubleshooting", "Cloud Run deep-dive".4---56# GCP Specialist78Structured investigation for Google Cloud workloads. Five phases: gather context,9diagnose, design, recommend, verify.1011## Arguments1213- `$0` — project context, service scope, or problem description. Required.1415---1617## Phase 1: Context Gathering18191. Identify the organization, folders, project(s), and services in scope.202. Glob for IaC in the working directory: `**/*.tf`, `**/*.yaml` (Config Connector), `**/*.jinja` (Deployment Manager legacy).213. If gcloud CLI access is available:22 ```bash23 gcloud config list24 gcloud projects list25 gcloud auth list26 ```274. List enabled APIs in the current project:28 ```bash29 gcloud services list --enabled --format="value(config.name)"30 ```3132---3334## Phase 2: Diagnosis3536**Compute / containers:**3738```bash39gcloud compute instances list40gcloud container clusters list41gcloud run services list42```4344**IAM / identity:**4546```bash47gcloud projects get-iam-policy <project>48gcloud iam service-accounts list49gcloud iam workload-identity-pools list --location=global50```5152**Networking:**5354```bash55gcloud compute networks list56gcloud compute firewall-rules list57gcloud compute routers list58```5960**Serverless / events:**6162```bash63gcloud functions list64gcloud pubsub topics list65gcloud pubsub subscriptions list66```6768**Cost / quotas:**6970```bash71gcloud compute project-info describe --format="yaml(quotas)"72gcloud logging read 'resource.type="gce_instance"' --limit=20 --format=json73```7475---7677## Phase 3: Design / Root-Cause Analysis7879Map symptoms to causes:8081| Symptom | Common Causes | Check |82| ---------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------ |83| GKE pod AuthN fails | Workload Identity not bound, KSA/GSA annotation mismatch | `kubectl describe sa` + `gcloud iam service-accounts get-iam-policy` |84| Cloud Run cold starts | min-instances=0, cold container image | `gcloud run services describe` → min-instances, image size |85| GCS AccessDenied | Uniform vs fine-grained mismatch, missing `roles/storage.objectViewer` | `gsutil iam get` + project-level IAM |86| Pub/Sub messages stuck | Subscription ack deadline too short, consumer crashed | `gcloud pubsub subscriptions describe` + dead-letter config |87| BigQuery slow query | Missing clustering/partitioning, full table scan | Query plan review, DRY_RUN pricing |88| VPC connectivity fail | Firewall default-deny, missing Private Google Access | `gcloud compute firewall-rules list` + subnet Private Google Access flag |8990Cite resource self-link or `file:line` for every finding.9192---9394## Phase 4: Recommendations9596Output findings in priority order:9798```99[CRITICAL] <title>100Resource: <self-link or file:line>101Issue: <one sentence>102Evidence: <gcloud output or code snippet>103Fix: <specific change, with Terraform/Config Connector diff>104Trade-off: <alternative and its downside, if meaningful>105```106107- Order: CRITICAL → WARNING → INFO.108- For IaC fixes, show the exact Terraform or Config Connector diff.109- Reference relevant docs in `references/` where applicable.110111---112113## Phase 5: Verification114115After fixes are applied:1161171. Re-run the diagnostic command that surfaced the issue.1182. For Workload Identity changes: `gcloud iam service-accounts get-iam-policy` and live pod token request.1193. For firewall changes: `gcloud compute firewall-rules list` + connectivity probe.1204. For IAM changes: `gcloud projects get-iam-policy --flatten="bindings[].members"` to see effective membership.1215. Check Cloud Monitoring dashboards and Error Reporting — no new incidents should be open.122123---124125## Reference Docs126127Consult `references/` for decision guides:128129| File | When to use |130| ------------------ | -------------------------------------------------------- |131| `compute.md` | GKE, Cloud Run, GCE selection and sizing |132| `serverless.md` | Cloud Functions, Pub/Sub, Cloud Tasks, Eventarc |133| `storage.md` | GCS, Filestore, BigQuery, Cloud SQL, Spanner |134| `networking.md` | VPC, Cloud Load Balancing, Cloud Armor, Cloud CDN |135| `iam.md` | IAM hierarchy, Workload Identity, Service Accounts |136| `observability.md` | Cloud Monitoring, Logging, Trace, Error Reporting |137| `iac-patterns.md` | Terraform, Config Connector, Deployment Manager patterns |
kaiohenricunha