GCP Collector

The GCP collector discovers and continuously monitors Google Cloud Platform infrastructure across compute, networking, storage, database, and serverless services. It connects to one or more GCP projects using a service account and periodically scans all resources, publishing configuration items and relationships for processing.

What Gets Discovered

The collector discovers 16 CI types across 8 GCP services:

All GCP resources have explicit names, so the CI name always matches the resource name in GCP (no tag-guessing like AWS).

Prerequisites

• A GCP project with billing enabled
• A service account with a downloaded key JSON file
• The following APIs enabled on each project you want to collect:
  • Compute Engine API
  • Cloud Resource Manager API
  • Cloud SQL Admin API
  • Kubernetes Engine API
  • Cloud Functions API
  • Cloud Run Admin API
  • Identity and Access Management (IAM) API
  • Cloud Storage API (enabled by default)

The collector only makes read-only API calls. No write permissions are needed or used.

IAM Role

Create a custom IAM role with the following permissions and bind it to the service account. This is the minimum set of permissions required for full discovery.

title: Parascope CMDB Reader
description: Read-only access for Parascope infrastructure discovery
permissions:
  # Compute Engine
  - compute.instances.list
  - compute.instances.get
  - compute.disks.list
  - compute.disks.get
  - compute.snapshots.list
  - compute.snapshots.get
  - compute.networks.list
  - compute.networks.get
  - compute.subnetworks.list
  - compute.subnetworks.get
  - compute.firewalls.list
  - compute.firewalls.get
  - compute.forwardingRules.list
  - compute.forwardingRules.get
  - compute.backendServices.list
  - compute.backendServices.get
  - compute.instanceGroups.list
  - compute.instanceGroups.get
  - compute.zones.list
  - compute.regions.list

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

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

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

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

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

  # IAM (service accounts only)
  - iam.serviceAccounts.list
  - iam.serviceAccounts.get

  # Resource Manager (project discovery)
  - resourcemanager.projects.list
  - resourcemanager.projects.get

Alternatively, you can use the built-in roles/viewer role, which grants broader read access but is simpler to configure. The custom role above follows least-privilege.

Configuration

Each GCP project (or set of projects) is configured as a Parascope source. Configure the service account credentials and optional project filtering:

Multi-Project Setup

The GCP collector supports automatic multi-project discovery. A single service account can collect from multiple GCP projects without additional configuration.

Auto-discovery: On each collection cycle, the collector calls the Resource Manager API (projects.list()) to discover all projects the service account has access to. Projects not in ACTIVE state are skipped automatically.

Allowlist/denylist filtering: Use gcp_project_allowlist to restrict collection to specific project IDs, or gcp_project_denylist to exclude specific projects. If both are set, only the allowlist is used.

Cross-project IAM: Grant the service account the custom IAM role (or roles/viewer) on each target project. A single service account in a central project can be granted roles across multiple projects via IAM bindings, with no impersonation needed.

Graceful fallback: If the service account does not have the resourcemanager.projects.list permission, project auto-discovery is skipped. In this case, configure the projects explicitly using gcp_project_allowlist. The collector handles the permission error gracefully and falls back to the explicit list.

Each project has independent health tracking and circuit breaking. A misconfigured or unreachable project does not block collection from other healthy projects.

Collected Resources

Compute

Instances are collected via aggregatedList (all zones in one call). Terminated instances are excluded. Configuration tracked in change history includes machine type, status, zone, network interfaces (internal/external IPs, VPC, subnet), attached disks, bound service accounts, network tags, labels, IP forwarding, and deletion protection.

Persistent disks are collected via aggregatedList. Configuration includes disk type, size, zone, status, labels, and source image or snapshot.

Disk snapshots are collected globally per project. Configuration includes source disk, storage size, status, and labels.

Kubernetes (GKE)

GKE clusters capture control plane metadata including Kubernetes version, network configuration (VPC, subnet), node pool references, cluster autoscaling, private cluster settings, master authorized networks, and release channel.

GKE node pools capture machine type, disk size, autoscaling configuration, node count, service account, and managed instance group reference.

Networking

VPC networks capture auto-mode status, routing mode, peering connections, and subnets.

Subnets capture IP CIDR range, region, private Google access, flow log configuration, and secondary ranges (for GKE pod/service CIDRs).

Firewall rules capture direction (ingress/egress), priority, action (allow/deny), protocol/port rules, source/destination ranges, target tags, and whether the rule is disabled or has logging enabled. Changes to firewall rules are tracked in change history.

Load Balancing

Forwarding rules capture IP address, port range, protocol, target backend service or target pool, network tier, and load balancing scheme (internal vs external).

Backend services capture protocol, port, health check references, backends (instance groups), session affinity, and load balancing mode.

Storage

Cloud Storage buckets are collected globally per project. Configuration includes location, storage class, versioning status, lifecycle rules, labels, and public access prevention settings.

Database

Cloud SQL instances capture database version (MySQL, PostgreSQL, SQL Server), tier (machine type), storage configuration, availability type (zonal/regional HA), backup configuration, private/public IP addresses, and maintenance window.

Serverless

Cloud Functions (v2 only) capture runtime, entry point, trigger type, available memory, timeout, VPC connector, service account, environment variables, and build configuration.

Cloud Run services capture container image, CPU/memory limits, scaling configuration (min/max instances), VPC connector, service account, ingress settings, and latest revision.

Identity

Service accounts capture email, display name, unique ID, disabled status, and description. Service accounts are the identity binding on GCP compute resources (instances, functions, Cloud Run, GKE node pools), making them essential for relationship completeness.

Relationships

The collector maps the following relationships between GCP resources:

This gives you a navigable GCP topology: project, VPC, subnet, instances, plus firewall rule coverage, disk attachment chains, load balancer membership, GKE cluster structure, and service account bindings across compute, serverless, and Kubernetes workloads.

Note: gcp.sql_instance, gcp.function, and gcp.run_service relationships to VPC networks are only created when the resource has a private IP or VPC connector configured. Public-only resources have no VPC relationship.

Cross-Source Correlation

Cross-source correlation links GCP resources to other Parascope sources:

• gcp.gke_cluster to kubernetes.cluster -- matched by cluster name or API server endpoint, linking GKE clusters to Kubernetes collector targets
• gcp.instance to kubernetes.node -- matched by provider ID (gce://project/zone/instance-name in the node's spec.providerID), linking GCE instances backing GKE nodes

Known Limitations

Shared VPC: GCP Shared VPC uses a host project to own VPC networks and subnets, while service projects consume them. With per-project collection, VPC and subnets appear under the host project, but instances in service projects cannot resolve runs_on relationships to those subnets (different project scope). Networking relationships will be silently absent for Shared VPC users. Resources are still collected, but the cross-project VPC links are missing.

Cloud Functions v2 only: The collector uses the Cloud Functions v2 API. First-generation Cloud Functions are not collected. If your environment has v1 functions, they will not appear in Parascope.

Troubleshooting

Invalid service account JSON

If you see authentication errors at startup, the gcp_service_account_json value is malformed or incomplete. Verify you are providing the entire contents of the downloaded JSON key file, not just the private key. The JSON must include type, project_id, private_key_id, private_key, client_email, and client_id fields.

Permission denied

The collector logs PermissionDenied errors per API call. If you see these, the service account is missing a permission. Compare the error message's method against the IAM role above and add the missing permission. Common causes:

• The custom role was not bound to the service account on the target project
• A newer version of the collector added a new API call not in your existing role

Project discovery failure

If you see errors from resourcemanager.projects.list, the service account does not have the resourcemanager.projects.list permission. Either add the permission or configure projects explicitly using gcp_project_allowlist. The collector falls back gracefully to the explicit list.

API not enabled

If you see ServiceUnavailable or PermissionDenied errors for a specific service (e.g., Cloud SQL, GKE), the corresponding API may not be enabled on the GCP project. Enable it in the Google Cloud Console under APIs and Services. The collector continues collecting other resource types when one API is not enabled.

Rate limiting

GCP APIs have per-project rate limits. The Google Cloud client libraries include built-in exponential backoff with jitter for rate-limited requests (HTTP 429). You do not need to take action. If collection is frequently slow due to throttling on projects with large resource counts, increase the collection interval.

No resources collected

If the collector runs without errors but no CIs appear, verify:

• The project ID in your configuration matches an active GCP project
• The service account has access to the target project (check IAM bindings in the Cloud Console)
• The project has resources deployed (the collector skips empty projects gracefully)
• APIs are enabled for the resource types you expect to see

Related Documentation

• Managing Collectors -- Collector health and configuration
• Architecture -- System design and CI type registry
• CI Types -- Complete CI type reference