Skip to main content
The Google Cloud Platform plugin provides access to the following resources from GCP:
  • Compute Engine Instances
  • Persistent Disks
  • Cloud SQL Instances
  • Cloud Storage Buckets
  • Load Balancers (URL Maps)
  • Backend Services
  • Target Pools
  • GKE Clusters and Node Pools
  • Cloud Functions (v1 and v2)
  • Cloud Run Services
Compute Engine Instances:
  • CPU Utilization
  • CPU Usage Time
  • Disk Read/Write Bytes
  • Disk Read/Write Operations
  • Network Received/Sent Bytes
  • Network Received/Sent Packets
  • Memory Balloon RAM Used/Size
Cloud SQL Instances:
  • CPU Utilization
  • CPU Usage Time
  • Disk Bytes Used/Quota
  • Disk Read/Write Operations
  • Memory Utilization/Usage/Quota
  • Network Connections
  • Network Received/Sent Bytes
  • Replication Replica Lag
  • Database Uptime
  • get_realtime_compute_instance_status: Get real-time status information for a Compute Engine instance
  • get_cloud_sql_instance_status: Get status information for a Cloud SQL database instance

​
Prerequisites

You should have GCP credentials configured through one of the following methods:
  • Application Default Credentials (ADC): Set up using gcloud auth application-default login (recommended for local development and cloud environments). Requires the gcloud CLI to be installed.
  • Service Account Key File: Create and download a service account key file from the GCP Console
The plugin follows the standard GCP credential provider chain.

​
Required Permissions

The GCP plugin requires read-only access to various GCP resources. Below is the recommended IAM (Identity and Access Management) configuration. The simplest approach is to assign the built-in Viewer role at the project level: 
# Get your project ID
PROJECT_ID=$(gcloud config get-value project)

# Assign Viewer role to your service account or user
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member=serviceAccount:YOUR-SERVICE-ACCOUNT@$PROJECT_ID.iam.gserviceaccount.com \
  --role=roles/viewer
This provides read access to all resources in the project, which is sufficient for the plugin to build the knowledge graph and retrieve metrics. For production environments, create a custom role with only the permissions needed by Unpage: 
title: "Unpage Reader"
description: "Minimal read-only permissions for Unpage infrastructure knowledge graph"
stage: "GA"
includedPermissions:
  # Compute Engine
  - compute.instances.get
  - compute.instances.list
  - compute.disks.get
  - compute.disks.list
  - compute.regions.list
  - compute.zones.list
  - compute.urlMaps.get
  - compute.urlMaps.list
  - compute.backendServices.get
  - compute.backendServices.list
  - compute.targetPools.get
  - compute.targetPools.list

  # Cloud SQL
  - cloudsql.instances.get
  - cloudsql.instances.list

  # Cloud Storage
  - storage.buckets.get
  - storage.buckets.list

  # GKE
  - container.clusters.get
  - container.clusters.list

  # Cloud Functions
  - cloudfunctions.functions.get
  - cloudfunctions.functions.list

  # Cloud Run
  - run.services.get
  - run.services.list

  # Cloud Monitoring (for metrics)
  - monitoring.timeSeries.list

  # Cloud Logging (for logs)
  - logging.logEntries.list

  # Resource Manager
  - resourcemanager.projects.get
To create and assign this custom role: 
# Save the YAML above to a file named unpage-reader-role.yaml

# Create the custom role
gcloud iam roles create unpageReader \
  --project=$PROJECT_ID \
  --file=unpage-reader-role.yaml

# Assign the custom role
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member=serviceAccount:YOUR-SERVICE-ACCOUNT@$PROJECT_ID.iam.gserviceaccount.com \
  --role=projects/$PROJECT_ID/roles/unpageReader

​
Permissions Breakdown

The custom role includes permissions for:
  • Compute Engine: Read access to VM instances, persistent disks, and load balancing resources
  • Cloud SQL: Read access to database instances
  • Cloud Storage: Read access to storage buckets
  • GKE: Read access to Kubernetes clusters
  • Cloud Functions: Read access to serverless functions
  • Cloud Run: Read access to containerized services
  • Cloud Monitoring: Read access to metrics for all resources
  • Cloud Logging: Read access to logs for all resources
  • Resource Manager: List and read project information
These permissions are read-only and follow the principle of least privilege.

​
Configuration

Configure the GCP plugin by running uv run unpage configure or by editing the ~/.unpage/profiles/<profile_name>/config.yaml file: 
plugins:
  # ...
  gcp:
    enabled: true
    # Optional: specify project details
    settings:
      projects:
        my-project:
          name: "My GCP Project"
          project_id: "my-project-id"
          auth_method: "adc"  # Options: "adc", "service_account"
          # Optional: path to service account key file (required if auth_method is "service_account")
          # service_account_key_path: "/path/to/service-account-key.json"
          # Optional: restrict to specific regions (defaults to all regions)
          # regions:
          #   - "us-central1"
          #   - "us-east1"
If no project is specified, the plugin will use the default project from your gcloud configuration.

​
Authentication Methods

  • adc: Uses Application Default Credentials (set up via gcloud auth application-default login)
  • service_account: Uses a service account key file (requires service_account_key_path)

​
Tools

The GCP plugin provides the following tools to Agents and MCP Clients:

get_realtime_compute_instance_status

Get real-time status information for a Compute Engine instance directly from GCP API.Arguments
​
instance_name
string
required
The Compute Engine instance name.
​
zone
string
required
The GCP zone where the instance is located (e.g., “us-central1-a”).
​
project_id
string
The GCP project ID. If not provided, uses the default project from configuration.
Returns dict | string: A dictionary containing instance status information or an error message if the instance couldn’t be found.Example response:
{
  "name": "my-instance",
  "status": "RUNNING",
  "machineType": "e2-medium",
  "zone": "us-central1-a",
  "cpuPlatform": "Intel Broadwell",
  "networkInterfaces": [
    {
      "networkIP": "10.128.0.2",
      "accessConfigs": [
        {
          "natIP": "34.123.45.67"
        }
      ]
    }
  ]
}

get_cloud_sql_instance_status

Get status information for a Cloud SQL database instance.Arguments
​
instance_name
string
required
The Cloud SQL instance name.
​
project_id
string
The GCP project ID. If not provided, uses the default project from configuration.
Returns dict | string: A dictionary containing database instance status and configuration details or an error message if the instance couldn’t be found.Example response:
{
  "name": "my-database",
  "state": "RUNNABLE",
  "databaseVersion": "POSTGRES_14",
  "region": "us-central1",
  "settings": {
    "tier": "db-f1-micro",
    "dataDiskSizeGb": 10,
    "availabilityType": "ZONAL"
  },
  "ipAddresses": [
    {
      "type": "PRIMARY",
      "ipAddress": "10.1.2.3"
    }
  ]
}