gcp-troubleshoot

timbuchinger's avatarfrom timbuchinger

Troubleshoot GCP services using tool-first access (via MCP when available), falling back to the CLI only when necessary. Focus on Firestore, Cloud Run, networking, load balancers, IAM, Pub/Sub, Cloud SQL, and Storage.

⭐0stars🔀0forks📁View on GitHub🕐Updated Dec 28, 2025
[Incident Response]

When & Why to Use This Skill

The GCP Troubleshooting skill is a specialized agentic tool designed to diagnose and resolve issues across Google Cloud Platform services. By prioritizing tool-based access via MCP and falling back to the gcloud CLI, it streamlines the debugging process for Firestore, Cloud Run, Networking, IAM, and more. It focuses on scoped log analysis and metric interpretation to provide actionable remediation steps, significantly reducing Mean Time to Recovery (MTTR) for cloud infrastructure incidents.

Use Cases

  • Diagnose Cloud Run deployment failures, such as crash loops or IAM-related service connection issues, by analyzing revision logs and rollout history.
  • Troubleshoot complex networking issues including 5xx Load Balancer responses and VPC firewall denials using targeted log queries.
  • Identify and resolve IAM 'Permission Denied' errors by auditing principal-resource mismatches in GCP audit logs.
  • Debug Firestore performance bottlenecks, such as transaction contention or missing indexes, to ensure database scalability.
  • Investigate Pub/Sub delivery failures and Dead Letter Queue (DLQ) growth by inspecting subscription logs and endpoint health.
  • Resolve Cloud SQL connectivity and authentication failures by analyzing database flags and private network routing.
namegcp-troubleshoot
description"Troubleshoot GCP services using tool-first access (via MCP when available), falling back to the CLI only when necessary. Focus on Firestore, Cloud Run, networking, load balancers, IAM, Pub/Sub, Cloud SQL, and Storage."

GCP Troubleshooting Skill

General Guidance

Always attempt to investigate issues using tool-based access first (MCP tools if configured).
Only fall back to the GCP CLI (gcloud) when the tool cannot access required logs, metrics, or audit data.

All investigations should:

  1. Scope queries by service/resource type
  2. Restrict by time window
  3. Prefer targeted logs/metrics, not full dumps
  4. Diagnose root cause based on error type
  5. Suggest minimal, safe remediation steps

Core Services Covered

Firestore

Common issues:

  • PERMISSION_DENIED
  • Missing indexes
  • Transaction contention
  • Quota exceeded

Investigations:

  • Query Firestore logs filtered by resource.type="firestore_database"
  • Check latency, retries, aborted transactions

Cloud Run

Common issues:

  • Startup failures
  • Crash loops
  • IAM failures calling other services
  • Cold starts

Investigations:

  • Query Cloud Run logs (resource.type="cloud_run_revision")
  • Check revision rollout history
  • Look for Cloud SQL connector errors or storage access failures

Networking & Load Balancers

Common issues:

  • 5xx responses
  • Backend connection errors
  • Firewall denies

Investigations:

  • Query load balancer logs (resource.type="http_load_balancer")
  • Inspect backend health logs
  • Check VPC routes + firewall rules

IAM

Common issues:

  • PermissionDenied
  • Missing service account roles

Investigations:

  • Query audit logs: protoPayload.status.code != 0
  • Identify the principal, resource, and role mismatch

Pub/Sub

Common issues:

  • Failed push deliveries
  • Ack deadlines exceeded
  • DLQ accumulation

Investigations:

  • Filter subscription logs
  • Inspect subscriber errors and endpoint failures

Cloud SQL

Common issues:

  • Connection limit reached
  • Auth failures
  • Private network routing failures

Investigations:

  • Cloud SQL logs (resource.type="cloudsql_database")
  • Check database flags, failover events, connection counts

Storage Buckets

Common issues:

  • 403 Forbidden
  • Precondition checks
  • Signed URL failures

Investigations:

  • Inspect Storage logs (resource.type="gcs_bucket")
  • Check IAM, bucket policies, object existence

Workflow

  1. Identify target resource
  2. Query scoped logs
  3. Query metrics
  4. Query audit logs if access or permission failures occur
  5. Interpret patterns
  6. Suggest actionable fixes

When to Warn

  • Unscoped log queries
  • Very wide time ranges
  • Requests requiring IAM escalation