Skip to content

Architecture Graph

Jump to bottom
Anna edited this page Jun 25, 2026 · 1 revision

Module: Architecture Graph

Module flag: archgraph Enabled by default: yes

Overview

The Architecture Graph module exports a comprehensive, project-wide resource graph covering all 26 modules: serverless services, GKE workloads, networking, data stores, supply chain, IAM, and observability nodes — with dependency edges inferred from configuration, IAM bindings, and live telemetry (Cloud Trace + Istio/ASM).

This is the most powerful single tool in the server. Use it to generate architecture diagrams, perform root-cause analysis, map compliance boundaries, or identify configuration drift.

For a faster, event-driven-only graph, see Serverless Graph.

Enable This Module

GCP_PROJECT_ID=my-project ./aura-tracker-gcp --modules archgraph

Required GCP APIs

The Architecture Graph calls all service APIs. Enable the APIs for the resources you have:

gcloud services enable run.googleapis.com container.googleapis.com \
  compute.googleapis.com cloudfunctions.googleapis.com \
  pubsub.googleapis.com sqladmin.googleapis.com bigquery.googleapis.com \
  spanner.googleapis.com alloydb.googleapis.com firestore.googleapis.com \
  redis.googleapis.com monitoring.googleapis.com cloudtrace.googleapis.com \
  artifactregistry.googleapis.com cloudbuild.googleapis.com \
  cloudresourcemanager.googleapis.com iam.googleapis.com

Required IAM Permissions

A superset of all module roles. At minimum:

roles/run.viewer
roles/container.viewer
roles/compute.networkViewer
roles/cloudfunctions.viewer
roles/pubsub.viewer
roles/monitoring.viewer
roles/cloudtrace.user
roles/iam.securityReviewer
roles/artifactregistry.reader
roles/cloudbuild.builds.viewer

Tools

gcp_export_architecture_graph

Exports the full project architecture graph in three parallel batches.

Parameters:

Name Required Description
project_id yes GCP project ID
region no Filter to a specific region
max_nodes no Cap on nodes returned
include_observability no Include trace and mesh edges (default: true)

Execution:

Batch What it discovers
Batch 1 (20 parallel listers) Cloud Run, Cloud Functions, GKE clusters, Pub/Sub, Cloud SQL, BigQuery, Spanner, AlloyDB, Firestore, Memorystore, Artifact Registry, Cloud Build, Service Directory, Load Balancers, VPCs, Eventarc, Scheduler, Workflows, Tasks, Service Accounts
Batch 2 (per-cluster parallel) GKE Deployments, StatefulSets, DaemonSets, Jobs, CronJobs, Services, Ingresses
Batch 3 (observability) Cloud Trace span dependency edges, Istio/ASM mesh telemetry edges

Edge inference:

Evidence source Edge type
K8s Service selectors → pod labels deployed_on
Cloud SQL annotation on Cloud Run connects_to
Pub/Sub push subscription endpoint matches service URL subscribes_to
IAM binding (service account → resource) bound_to_sa
Cloud Trace parent/child spans trace_calls
Istio/ASM telemetry mesh_calls

Returns: JSON graph with nodes (URN, kind, name, region, labels, image, service account), typed directed edges (with evidence type and confidence), and hierarchical groups (project → region → network → cluster/namespace).

Note: Results are cached for 5 minutes. Large projects (5+ clusters, 50+ services) may take 40–60 seconds on first call. Adjust GRAPH_TIMEOUT_SECONDS if needed.

Prompt Examples

Full export

"Export the full architecture graph for project my-project."

Architecture diagram

"Export the architecture graph for project my-project and describe the top-level service groups and their inter-dependencies."

Supply chain traceability

"Which container images in project my-project were built by Cloud Build and from which Artifact Registry repositories are they pulled?"

Drift detection

"Compare the K8s service selector configuration with the actual traffic patterns from Cloud Trace for GKE cluster prod-cluster in project my-project."

Compliance mapping

"Map all service accounts in project my-project to the Cloud Run services and GKE workloads they are assigned to."

Related Modules

Module flag Why you'd combine it
serverlessgraph Faster event-driven-only graph
topology Deeper single-service dependency detail
coverage Layer observability completeness onto the graph
aura Layer health scores onto the graph nodes

Clone this wiki locally