Skip to content
This repository was archived by the owner on Jul 7, 2026. It is now read-only.

Commit d7944b2

Browse files
tvdaptibletvdaptible
committed
gcp plugin docs
1 parent c7ddebc commit d7944b2

4 files changed

Lines changed: 445 additions & 0 deletions

File tree

‎docs/docs.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -63,6 +63,7 @@
6363
"plugins/aptible",
6464
"plugins/aws",
6565
"plugins/azure",
66+
"plugins/gcp",
6667
"plugins/core",
6768
"plugins/datadog",
6869
"plugins/github",

‎docs/plugins/gcp.mdx‎

Lines changed: 276 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,276 @@
1+
---
2+
title: GCP
3+
---
4+
5+
The [Google Cloud Platform](https://cloud.google.com/) plugin provides access to the following
6+
resources from GCP:
7+
8+
<AccordionGroup>
9+
<Accordion title="Knowledge Graph nodes" icon="diagram-project">
10+
- Compute Engine Instances
11+
- Persistent Disks
12+
- Cloud SQL Instances
13+
- Cloud Storage Buckets
14+
- Load Balancers (URL Maps)
15+
- Backend Services
16+
- Target Pools
17+
- GKE Clusters and Node Pools
18+
- Cloud Functions (v1 and v2)
19+
- Cloud Run Services
20+
</Accordion>
21+
22+
<Accordion title="Metrics" icon="chart-line">
23+
**Compute Engine Instances:**
24+
- CPU Utilization
25+
- CPU Usage Time
26+
- Disk Read/Write Bytes
27+
- Disk Read/Write Operations
28+
- Network Received/Sent Bytes
29+
- Network Received/Sent Packets
30+
- Memory Balloon RAM Used/Size
31+
32+
**Cloud SQL Instances:**
33+
- CPU Utilization
34+
- CPU Usage Time
35+
- Disk Bytes Used/Quota
36+
- Disk Read/Write Operations
37+
- Memory Utilization/Usage/Quota
38+
- Network Connections
39+
- Network Received/Sent Bytes
40+
- Replication Replica Lag
41+
- Database Uptime
42+
</Accordion>
43+
44+
<Accordion title="MCP Tools" icon="wrench">
45+
- **get_realtime_compute_instance_status**: Get real-time status information for a Compute Engine instance
46+
- **get_cloud_sql_instance_status**: Get status information for a Cloud SQL database instance
47+
</Accordion>
48+
</AccordionGroup>
49+
50+
51+
## Prerequisites
52+
53+
You should have GCP credentials configured through one of the following methods:
54+
55+
- **gcloud CLI**: Use `gcloud auth login` to authenticate with the [gcloud CLI](https://cloud.google.com/sdk/gcloud) (recommended for local development)
56+
- **Application Default Credentials (ADC)**: Recommended for cloud environments, set up using `gcloud auth application-default login`
57+
- **Service Account Key File**: Create and download a service account key file from the GCP Console
58+
59+
The plugin follows the [standard GCP credential provider chain](https://cloud.google.com/docs/authentication/application-default-credentials).
60+
61+
### Required Permissions
62+
63+
The GCP plugin requires read-only access to various GCP resources. Below is the recommended IAM (Identity and Access Management) configuration.
64+
65+
#### Option 1: Use Built-in Viewer Role (Recommended for Getting Started)
66+
67+
The simplest approach is to assign the built-in **Viewer** role at the project level:
68+
69+
```bash
70+
# Get your project ID
71+
PROJECT_ID=$(gcloud config get-value project)
72+
73+
# Assign Viewer role to your service account or user
74+
gcloud projects add-iam-policy-binding $PROJECT_ID \
75+
--member=serviceAccount:YOUR-SERVICE-ACCOUNT@$PROJECT_ID.iam.gserviceaccount.com \
76+
--role=roles/viewer
77+
```
78+
79+
This provides read access to all resources in the project, which is sufficient for the plugin to build the knowledge graph and retrieve metrics.
80+
81+
#### Option 2: Custom Role with Minimal Permissions (Recommended for Production)
82+
83+
For production environments, create a custom role with only the permissions needed by Unpage:
84+
85+
```yaml
86+
title: "Unpage Reader"
87+
description: "Minimal read-only permissions for Unpage infrastructure knowledge graph"
88+
stage: "GA"
89+
includedPermissions:
90+
# Compute Engine
91+
- compute.instances.get
92+
- compute.instances.list
93+
- compute.disks.get
94+
- compute.disks.list
95+
- compute.regions.list
96+
- compute.zones.list
97+
- compute.urlMaps.get
98+
- compute.urlMaps.list
99+
- compute.backendServices.get
100+
- compute.backendServices.list
101+
- compute.targetPools.get
102+
- compute.targetPools.list
103+
104+
# Cloud SQL
105+
- cloudsql.instances.get
106+
- cloudsql.instances.list
107+
108+
# Cloud Storage
109+
- storage.buckets.get
110+
- storage.buckets.list
111+
112+
# GKE
113+
- container.clusters.get
114+
- container.clusters.list
115+
116+
# Cloud Functions
117+
- cloudfunctions.functions.get
118+
- cloudfunctions.functions.list
119+
120+
# Cloud Run
121+
- run.services.get
122+
- run.services.list
123+
124+
# Cloud Monitoring (for metrics)
125+
- monitoring.timeSeries.list
126+
127+
# Cloud Logging (for logs)
128+
- logging.logEntries.list
129+
130+
# Resource Manager
131+
- resourcemanager.projects.get
132+
```
133+
134+
To create and assign this custom role:
135+
136+
```bash
137+
# Save the YAML above to a file named unpage-reader-role.yaml
138+
139+
# Create the custom role
140+
gcloud iam roles create unpageReader \
141+
--project=$PROJECT_ID \
142+
--file=unpage-reader-role.yaml
143+
144+
# Assign the custom role
145+
gcloud projects add-iam-policy-binding $PROJECT_ID \
146+
--member=serviceAccount:YOUR-SERVICE-ACCOUNT@$PROJECT_ID.iam.gserviceaccount.com \
147+
--role=projects/$PROJECT_ID/roles/unpageReader
148+
```
149+
150+
#### Permissions Breakdown
151+
152+
The custom role includes permissions for:
153+
154+
- **Compute Engine**: Read access to VM instances, persistent disks, and load balancing resources
155+
- **Cloud SQL**: Read access to database instances
156+
- **Cloud Storage**: Read access to storage buckets
157+
- **GKE**: Read access to Kubernetes clusters
158+
- **Cloud Functions**: Read access to serverless functions
159+
- **Cloud Run**: Read access to containerized services
160+
- **Cloud Monitoring**: Read access to metrics for all resources
161+
- **Cloud Logging**: Read access to logs for all resources
162+
- **Resource Manager**: List and read project information
163+
164+
These permissions are read-only and follow the principle of least privilege.
165+
166+
167+
## Configuration
168+
169+
Configure the GCP plugin by running `uv run unpage configure` or by editing
170+
the `~/.unpage/profiles/<profile_name>/config.yaml` file:
171+
172+
```yaml
173+
plugins:
174+
# ...
175+
gcp:
176+
enabled: true
177+
# Optional: specify project details
178+
settings:
179+
projects:
180+
my-project:
181+
name: "My GCP Project"
182+
project_id: "my-project-id"
183+
auth_method: "gcloud" # Options: "gcloud", "adc", "service_account"
184+
# Optional: path to service account key file (required if auth_method is "service_account")
185+
# service_account_key_path: "/path/to/service-account-key.json"
186+
# Optional: restrict to specific regions (defaults to all regions)
187+
# regions:
188+
# - "us-central1"
189+
# - "us-east1"
190+
```
191+
192+
If no project is specified, the plugin will use the default project from your gcloud configuration.
193+
194+
### Authentication Methods
195+
196+
- **`gcloud`**: Uses credentials from the gcloud CLI (recommended for local development)
197+
- **`adc`**: Uses Application Default Credentials (recommended for cloud environments)
198+
- **`service_account`**: Uses a service account key file (requires `service_account_key_path`)
199+
200+
## Tools
201+
202+
The GCP plugin provides the following tools to Agents and MCP Clients:
203+
204+
<Card title="get_realtime_compute_instance_status">
205+
Get real-time status information for a Compute Engine instance directly from GCP API.
206+
207+
**Arguments**
208+
<ParamField path="instance_name" type="string" required>
209+
The Compute Engine instance name.
210+
</ParamField>
211+
<ParamField path="zone" type="string" required>
212+
The GCP zone where the instance is located (e.g., "us-central1-a").
213+
</ParamField>
214+
<ParamField path="project_id" type="string">
215+
The GCP project ID. If not provided, uses the default project from configuration.
216+
</ParamField>
217+
218+
**Returns** `dict | string`: A dictionary containing instance status information or an error message if the instance couldn't be found.
219+
220+
Example response:
221+
```json
222+
{
223+
"name": "my-instance",
224+
"status": "RUNNING",
225+
"machineType": "e2-medium",
226+
"zone": "us-central1-a",
227+
"cpuPlatform": "Intel Broadwell",
228+
"networkInterfaces": [
229+
{
230+
"networkIP": "10.128.0.2",
231+
"accessConfigs": [
232+
{
233+
"natIP": "34.123.45.67"
234+
}
235+
]
236+
}
237+
]
238+
}
239+
```
240+
</Card>
241+
<br />
242+
243+
<Card title="get_cloud_sql_instance_status">
244+
Get status information for a Cloud SQL database instance.
245+
246+
**Arguments**
247+
<ParamField path="instance_name" type="string" required>
248+
The Cloud SQL instance name.
249+
</ParamField>
250+
<ParamField path="project_id" type="string">
251+
The GCP project ID. If not provided, uses the default project from configuration.
252+
</ParamField>
253+
254+
**Returns** `dict | string`: A dictionary containing database instance status and configuration details or an error message if the instance couldn't be found.
255+
256+
Example response:
257+
```json
258+
{
259+
"name": "my-database",
260+
"state": "RUNNABLE",
261+
"databaseVersion": "POSTGRES_14",
262+
"region": "us-central1",
263+
"settings": {
264+
"tier": "db-f1-micro",
265+
"dataDiskSizeGb": 10,
266+
"availabilityType": "ZONAL"
267+
},
268+
"ipAddresses": [
269+
{
270+
"type": "PRIMARY",
271+
"ipAddress": "10.1.2.3"
272+
}
273+
]
274+
}
275+
```
276+
</Card>

‎src/unpage/agent/templates/investigate_gcp_cloud_sql_error.yaml‎

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
description: >
2+
Use this agent to investigate errors with GCP Cloud SQL database instances and diagnose connection or performance issues
3+
4+
prompt: >
5+
- Extract the Cloud SQL instance name and error details from the incoming alert
6+
- Use the graph tools to find the Cloud SQL instance in the knowledge graph
7+
- Use the GCP MCP tools to fetch real-time status information about the database instance
8+
- Check recent metrics to identify issues:
9+
- CPU utilization (high CPU may indicate inefficient queries)
10+
- Memory usage (high memory may indicate connection pool exhaustion)
11+
- Disk usage (running out of disk space)
12+
- Network connections (too many or too few active connections)
13+
- Replication lag (if this is a replica instance)
14+
- Review recent logs from Cloud Logging to identify:
15+
- Connection failures or authentication errors
16+
- Slow query warnings
17+
- Database errors or crashes
18+
- Configuration changes
19+
- Check for related resources:
20+
- Check if this is a replica and whether the master instance is healthy
21+
- Identify any replicas if this is a master instance
22+
- Check backup configuration and recent backup status
23+
- Determine if a human SRE should investigate further
24+
- Post a status update to the PagerDuty incident with:
25+
- 1-2 sentences summarizing what happened and the suggested action
26+
- Key metrics and log findings that led to your conclusion
27+
- Whether this is a capacity issue, configuration problem, or application issue
28+
- Don't assume or make things up; say you don't know if you don't
29+
30+
tools:
31+
- "gcp_*"
32+
- "core_current_datetime"
33+
- "core_calculate"
34+
- "graph_get_resource_details"
35+
- "graph_get_resource_map"
36+
- "graph_search_resources"
37+
- "graph_get_neighboring_resources"
38+
- "metrics_get_metrics_for_node"
39+
- "metrics_list_available_metrics_for_node"
40+
- "pagerduty_get_incident_details"
41+
# - "pagerduty_post_status_update"
42+
43+
test_payloads:
44+
cloud_sql_high_cpu:
45+
payload: >
46+
{
47+
"incident": {
48+
"title": "GCP Cloud SQL High CPU - production-db in us-central1",
49+
"description": "Cloud SQL instance 'production-db' is experiencing high CPU utilization (92% average over 15 minutes). This may be caused by inefficient queries or increased load.",
50+
"created_at": "2024-01-15T14:20:00Z",
51+
"status": "triggered",
52+
"urgency": "high",
53+
"service": {
54+
"id": "PGCPMON",
55+
"type": "service_reference",
56+
"summary": "GCP Monitoring Service",
57+
"self": "https://api.pagerduty.com/services/PGCPMON",
58+
"html_url": "https://example.pagerduty.com/service-directory/PGCPMON"
59+
}
60+
}
61+
}
62+
63+
cloud_sql_connection_failure:
64+
payload: >
65+
{
66+
"incident": {
67+
"title": "GCP Cloud SQL Connection Failures - staging-postgres",
68+
"description": "Cloud SQL instance 'staging-postgres' is experiencing connection failures. Multiple applications are reporting 'could not connect to server' errors.",
69+
"created_at": "2024-01-15T09:15:00Z",
70+
"status": "triggered",
71+
"urgency": "high",
72+
"service": {
73+
"id": "PGCPMON",
74+
"type": "service_reference",
75+
"summary": "GCP Monitoring Service",
76+
"self": "https://api.pagerduty.com/services/PGCPMON",
77+
"html_url": "https://example.pagerduty.com/service-directory/PGCPMON"
78+
}
79+
}
80+
}
81+
82+
cloud_sql_replication_lag:
83+
payload: >
84+
{
85+
"incident": {
86+
"title": "GCP Cloud SQL High Replication Lag - read-replica-1",
87+
"description": "Cloud SQL read replica 'read-replica-1' has high replication lag (45 seconds behind master). This may cause stale reads for applications using this replica.",
88+
"created_at": "2024-01-15T16:30:00Z",
89+
"status": "triggered",
90+
"service": {
91+
"id": "PGCPMON",
92+
"type": "service_reference",
93+
"summary": "GCP Monitoring Service",
94+
"self": "https://api.pagerduty.com/services/PGCPMON",
95+
"html_url": "https://example.pagerduty.com/service-directory/PGCPMON"
96+
}
97+
}
98+
}

0 commit comments

Comments
 (0)