GCP Connector

The GCP connector integrates with Google Cloud Platform using service account credentials, providing 8 live tools and ETL ingestion of cloud resources into the knowledge graph.

Authentication

GCP authentication uses either a service account JSON key or a project ID with Application Default Credentials.

Service Account Key (Recommended)

Create a service account in your GCP project and download the JSON key.

{
  "name": "Production GCP",
  "source_type": "gcp",
  "config": {
    "service_account_json": {
      "type": "service_account",
      "project_id": "my-project-123",
      "private_key_id": "key-id",
      "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n",
      "client_email": "agentcy@my-project-123.iam.gserviceaccount.com",
      "client_id": "123456789",
      "auth_uri": "https://accounts.google.com/o/oauth2/auth",
      "token_uri": "https://oauth2.googleapis.com/token"
    },
    "project_id": "my-project-123"
  }
}

Variable	Required	Description
service_account_json / GCP_SERVICE_ACCOUNT_JSON	Yes (or use ADC)	Full service account JSON key object
project_id / GCP_PROJECT_ID	Yes	GCP project ID

Application Default Credentials

If Agentcy is running on GCP (GCE, GKE, Cloud Run), you can rely on Application Default Credentials by providing only the project ID:

{
  "name": "GCP via ADC",
  "source_type": "gcp",
  "config": {
    "project_id": "my-project-123"
  }
}

Creating a Service Account

1. Go to IAM & Admin > Service Accounts in the GCP Console
2. Click Create Service Account
3. Name it agentcy-connector
4. Grant the following roles:
   • Viewer (basic read access)
   • Storage Object Viewer (GCS object listing)
   • Kubernetes Engine Viewer (GKE cluster metadata)
   • Compute Viewer (GCE instance metadata)
5. Click Create Key > JSON and download the key file

TIP

For production use, create a custom role with only the specific permissions Agentcy needs instead of using the broad Viewer role.

Live Tools (8)

Tool	Description	Arguments
gcp_list_instances	List Compute Engine instances with status and metadata	zone?, filter?
gcp_get_instance	Get detailed info about a specific GCE instance	instance, zone
gcp_list_buckets	List Cloud Storage buckets in the project	prefix?
gcp_list_gke_clusters	List GKE clusters with status, node count, and version	region?
gcp_list_cloudsql_instances	List Cloud SQL instances with status and settings	filter?
gcp_list_service_accounts	List service accounts in the project	filter?
gcp_list_functions	List Cloud Functions with runtime and status	region?
gcp_list_pubsub_topics	List Pub/Sub topics in the project	filter?

Example: Agent Using GCP Tools

User: "What GKE clusters are running and how many nodes do they have?"

Agent: Let me check your GKE clusters.
→ Calls gcp_list_gke_clusters()
→ Returns 2 clusters: prod-cluster (3 nodes, v1.28), staging-cluster (1 node, v1.27)
→ Both are in RUNNING state in us-central1

User: "List my Cloud SQL instances"

Agent: I'll pull the Cloud SQL details.
→ Calls gcp_list_cloudsql_instances()
→ Returns instance names, tiers, regions, and status

ETL Ingestion

When you trigger a sync, the GCP connector ingests the following resources into the knowledge graph.

Nodes Created

Node Label	Properties	GCP Service
GCEInstance	name, zone, machine_type, status, internal_ip, external_ip, tags	Compute Engine
GCSBucket	name, location, storage_class, creation_time, versioning_enabled	Cloud Storage
GKECluster	name, region, status, node_count, master_version, network, subnetwork	Kubernetes Engine
GKENodePool	name, machine_type, disk_size_gb, node_count, autoscaling_min, autoscaling_max	Kubernetes Engine
IAMBinding	role, members, resource	IAM
ServiceAccount	email, display_name, disabled, project_id	IAM

Relationships Created

Relationship	From	To
RUNS_IN	GCEInstance	Zone
HAS_NODE_POOL	GKECluster	GKENodePool
HAS_BINDING	IAMBinding	ServiceAccount
USES	GCEInstance	ServiceAccount
HOSTS	GKECluster	GCEInstance
STORES_IN	GKECluster	GCSBucket
MEMBER_OF	ServiceAccount	IAMBinding

Graph Queries

-- Find all GCE instances by zone
MATCH (i:GCEInstance)
RETURN i.zone, count(i) AS instance_count, collect(i.machine_type) AS types
ORDER BY instance_count DESC

-- Find GKE clusters with their node pools and scaling config
MATCH (c:GKECluster)-[:HAS_NODE_POOL]->(np:GKENodePool)
RETURN c.name, c.status, np.name, np.machine_type,
       np.autoscaling_min, np.autoscaling_max

-- Audit service account permissions
MATCH (sa:ServiceAccount)<-[:HAS_BINDING]-(b:IAMBinding)
WHERE sa.email CONTAINS "agentcy"
RETURN sa.email, b.role

Configuration Reference

{
  "name": "Production GCP",
  "source_type": "gcp",
  "config": {
    "service_account_json": { "...": "..." },
    "project_id": "my-project-123",
    "regions": ["us-central1", "us-east1"],
    "sync_gce": true,
    "sync_gcs": true,
    "sync_gke": true,
    "sync_iam": true,
    "label_filters": {
      "env": ["production"]
    }
  }
}

Field	Type	Default	Description
service_account_json	object	--	Service account JSON key (or use ADC)
project_id	string	required	GCP project ID
regions	string[]	all	Regions to scan for regional resources
sync_gce	bool	true	Include Compute Engine instances
sync_gcs	bool	true	Include Cloud Storage buckets
sync_gke	bool	true	Include GKE clusters and node pools
sync_iam	bool	true	Include IAM bindings and service accounts
label_filters	object	--	Only ingest resources matching these labels

Troubleshooting

Error	Cause	Fix
PERMISSION_DENIED	Service account lacks required roles	Add the Viewer role or required granular permissions
NOT_FOUND	Project ID is incorrect or project does not exist	Verify the project ID in the GCP Console
INVALID_ARGUMENT	Malformed service account key JSON	Re-download the key file from the GCP Console
UNAUTHENTICATED	Service account key has been revoked or deleted	Generate a new key for the service account
RESOURCE_EXHAUSTED	API quota exceeded	Check quotas in APIs & Services > Quotas and request increases

Verifying Access

Test your service account from the command line:

# Activate the service account
gcloud auth activate-service-account --key-file=service-account.json

# Verify project access
gcloud projects describe my-project-123

# Test GCE access
gcloud compute instances list --project=my-project-123

# Test GKE access
gcloud container clusters list --project=my-project-123