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 [global-options] <command> [command-options] [arguments]
Example: gcpdiag projects <project-id> [--json]
Example: gcpdiag rules list

--project <project-id>
    Specifies the Google Cloud project ID to diagnose.

--billing-project <project-id>
    Sets the project ID to use for billing purposes, useful when diagnosing a project without active billing.

--log-level <level>
    Adjusts the verbosity of log output. Possible levels include debug, info, warning, error.

--output <format>
    Determines the output format of the diagnostic results. Options include text (default), json, and json-pretty.

--rule <rule-id>
    Executes only the specified diagnostic rule(s). Multiple rules can be provided as a comma-separated list.

--resource-type <type>
    Limits the diagnostic scan to specific types of resources (e.g., gce_instance, gke_cluster).

--run-in-gce
    Runs gcpdiag within a Google Compute Engine instance to diagnose issues related to the host VM.

--auth-url <url>
    Specifies a custom URL for the authentication server, for advanced authentication configurations.

--api-url <url>
    Sets a custom URL for the Google Cloud API endpoint, useful for private API access or testing.

--enable-gce-serial-port-access
    Enables access to the Google Compute Engine serial port, required for certain deep VM diagnostics. Requires appropriate IAM permissions.

projects <project-id>
    A subcommand used to initiate a diagnostic scan of a specific Google Cloud project.

rules list
    A subcommand to list all available diagnostic rules with their descriptions.

gcpdiag is a powerful open-source command-line tool designed to help users diagnose common issues and misconfigurations within their Google Cloud Platform projects. It automatically scans for unhealthy resources, security vulnerabilities, performance bottlenecks, and operational best practices violations by applying a comprehensive set of diagnostic rules. The tool provides actionable insights and recommended solutions, making it invaluable for SREs, developers, and cloud administrators to maintain the health, security, and efficiency of their GCP environments. It supports scanning entire projects or specific assets, and its output can be customized for various formats, including JSON and console-friendly text.

Running gcpdiag requires appropriate IAM permissions to access various Google Cloud resources and APIs. Depending on the project's size and the rules executed, it might generate a significant number of API calls, potentially affecting API rate limits or incurring operational costs. Not all diagnostic rules apply to all services or regions, and some may require specific Google Cloud APIs to be enabled.

gcpdiag can be installed using Python's package installer with pip install gcpdiag. Alternatively, it is available as a component of the gcloud CLI, installable via gcloud components install gcpdiag.

To effectively diagnose a project, the executing principal (user or service account) needs sufficient IAM roles. Commonly required roles include Project Viewer, Security Reviewer, and specific Viewer roles for services like Compute Engine, Kubernetes Engine, Cloud SQL, etc. Access to Cloud Logging and Monitoring data is also crucial for comprehensive analysis.

One of gcpdiag's strengths is its extensibility. Users and contributors can develop and submit new diagnostic rules, allowing the tool to adapt and provide insights into new services, emerging issues, or specific organizational best practices.

gcpdiag is an open-source tool developed by Google Cloud to empower users and support teams with self-service diagnostic capabilities. Its development emerged from the growing complexity of cloud environments and the need for automated troubleshooting. Actively maintained on GitHub, it continuously evolves with new diagnostic rules and features, reflecting the latest Google Cloud services and best practices.

gcloud(1), kubectl(1), gsutil(1), bq(1)