gcpdiag

Run gcpdiag on your project, returning all rules

$ gcpdiag lint --project [gcp_project_id]

$ gcpdiag lint --project [gcp_project_id] --hide-ok

$ gcpdiag lint --project [gcp_project_id] --auth-key [path/to/private_key]

$ gcpdiag lint --project [gcp_project_id] --within-days [number]

$ gcpdiag lint --help

gcpdiag run [--project PROJECT] [--scope SCOPE] [--resource RES] [--resource-type TYPE] [--filter FILTER] [OPTIONS]

--project PROJECT
    GCP project ID to diagnose (auto-detects if omitted)

--scope SCOPE
    Scan scope: auto, project, folder:ID, or org:ID (default: auto)

--resource RES
    Full resource name, e.g., projects/p/zones/z/instances/i

--resource-type TYPE
    Resource type filter, e.g., compute_instance, gke_cluster

--filter FILTER
    JQ-style filter for findings, e.g., .category == "compute"

--group-by GROUP
    Group output by resource or finding (default: resource)

--format FORMAT
    Output format: text, json, html (default: text)

--output FILE
    Save output to file

--skip-log-scanner
    Skip scanning audit logs (faster, less comprehensive)

--debug
    Enable debug logging

gcpdiag is an open-source command-line tool developed by Google Cloud for automatically diagnosing common issues and misconfigurations in Google Cloud Platform (GCP) environments. It supports scanning at project, folder, or organization scope, inspecting resources like Compute Engine VMs, GKE clusters, Cloud SQL instances, Pub/Sub topics, and IAM policies. The tool analyzes configurations, metrics, audit logs, and operational data to detect problems such as high CPU usage, missing firewalls, deprecated images, permission issues, and more. It provides detailed findings with severity levels (FAIL, WARN, OK), explanations, and remediation steps.

Run diagnostics with filters for specific resources or use cases, outputting results in text, JSON, or HTML formats. Ideal for SREs, DevOps teams, and support engineers to triage incidents quickly without manual log diving. Requires GCP authentication and appropriate IAM roles like roles/logging.viewer and roles/monitoring.viewer. Actively maintained on GitHub with community contributions.

Requires gcloud CLI authenticated with sufficient IAM permissions (e.g., Logging Viewer, Monitoring Viewer); scans can be slow/resource-intensive on large orgs; limited to supported finders/resources; preview findings may change.

pip install gcpdiag
Ensure gcloud auth application-default login and project set.

gcpdiag run --project=my-project --resource-type=gke_cluster
Diagnoses all GKE clusters in the project.

Developed by Google Cloud Customer Engineering team; first public release in 2021; open-sourced on GitHub (google/gcpdiag); regular updates add new finders for emerging GCP services; widely used in production support.

gcloud(1), gsutil(1)