Skip to content

Commit cc1693e

Browse files
tvdaptibletvdaptible
authored
feat: gcp plugin [SC-34604] (#208)
1 parent 073616f commit cc1693e

25 files changed

+4106
-8
lines changed

‎.pre-commit-config.yaml‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,8 @@ repos:
4343
hooks:
4444
# Check for type errors.
4545
- id: pyright
46-
entry: uv run --active pyright
46+
entry: uv run --active pyright --project=pyproject.toml
47+
pass_filenames: false
4748
exclude: |
4849
(?x)^
4950
pinned_hatchling_backend.py$

‎docs/docs.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -65,6 +65,7 @@
6565
"plugins/aptible",
6666
"plugins/aws",
6767
"plugins/azure",
68+
"plugins/gcp",
6869
"plugins/core",
6970
"plugins/datadog",
7071
"plugins/github",

‎docs/plugins/gcp.mdx‎

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

‎pyproject.toml‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,11 @@ dependencies = [
4848
"rich-gradient>=0.3.4",
4949
"expandvars>=1.1.2",
5050
"azure-mgmt-containerservice>=39.1.0",
51+
"google-auth>=2.40.3",
52+
"google-auth-httplib2>=0.2.0",
53+
"google-cloud-monitoring>=2.27.2",
54+
"google-cloud-logging>=3.12.1",
55+
"aiohttp>=3.11.18",
5156
]
5257

5358
[tool.hatch.metadata]

0 commit comments

Comments
 (0)