Monitoring Google Cloud Platform (GCP)

The supported operating systems of the GCP sensor are consistent with the host agent requirements. For more information, see Agent requirements.

The GCP sensor version determines whether a single Instana agent can monitor one or multiple GCP projects. To check your current sensors version, see Sensors version.

The following steps create a service account and provide Instana with the credentials it needs to make API calls on your behalf.

1. Access the Google Cloud credentials page for the project where you want to set up the Instana integration.

   For multi-project monitoring, you can create the service account in any GCP project you manage. The project where the service account is created is automatically included to other monitored projects.

2. Click CREATE CREDENTIALS > Service account.

   

3. In the Create service account page, enter a unique name for the service account, and click Create and continue.

4. Click Create and close.

To create a custom role, complete the following steps:

1. From the navigation menu, click Roles > Create custom role.
2. Enter the role title and description.
3. For the Role launch stage, select General Availability.

4. Click Add permissions.

   

   Assign the following minimal set of permissions:

   • monitoring.timeSeries.list
   • pubsub.subscriptions.list
   • pubsub.topics.list
   • resourcemanager.projects.get
   • cloudsql.instances.list
   • storage.buckets.list
   • run.revisions.list
   • run.services.list

   For multi-project monitoring, the following additional permissions are required:

   • resourcemanager.projects.list
   • resourcemanager.folders.list
   • serviceusage.services.use
   Note:

   To enable single-project monitoring, grant the custom role access at the individual project level. For more information, see Granting access to individual projects.
   Note:

   To enable multi-project monitoring, grant the custom role access at the folder level so all permissions are inherited by all child folders and projects. For more information, see Granting the service account access to folders or projects.

5. Click Create.

1. Select the account you created from the list of service accounts.

2. Select the Key tab, and click Add key.

3. Select Create new key.

4. Select the key type as JSON, and then click Create.

   

   Note:

   You need to record the location of the credential file where it is saved to complete the integration.

1. Add a field credentials_path to the configuration.yaml file with the path to the credentials file. See the following example:

   com.instana.plugin.gcp:
     poll_rate: 60 # How often Google's monitoring API is polled in seconds
     credentials_path: '/opt/instana/credentials/cred-gcp.json' # Path to service account credentials
     exclude_tags: ''
     include_tags: ''
   

After creating the service account, assign it the required IAM roles at the appropriate scope, either at the GCP folder level (to enable multi-project monitoring) or at the individual project level (for single-project monitoring). Repeat the following steps for each additional folder or project you want to grant the service account access to.

Enable the following GCP service API on each monitored project:

• Google Cloud Billing
• Cloud Monitoring API
• Compute Engine API
• Cloud Resource Manager API
• Cloud Run Admin API
• Cloud Storage API
• Cloud Datastore API
• Cloud SQL Admin API
• Cloud Pub/Sub API

• Service account was created following the Create service account procedure.
• Service account key was generated following the Generate service account key procedure.
• Access was granted by using the created custom role by following the Granting access at the folder level procedure.

To specify which projects to monitor, use the following agent configuration settings:

• folder_ids: A comma-separated list of GCP folder IDs. The agent discovers all projects within those folders by traversing the folder hierarchy recursively.
• project_ids: A comma-separated list of explicit GCP project IDs to monitor directly.

Both parameters are optional and can be used independently or together. The project ID embedded in the service account credentials file is always monitored regardless of these settings.

To enable multi-project monitoring for all GCP sensors, add folder_ids or project_ids (or both) to the global configuration block in the /opt/instana/agent/etc/instana/configuration.yaml file:

com.instana.plugin.gcp:
  poll_rate: 60
  credentials_path: '/opt/instana/credentials/cred-gcp.json'
  folder_ids: '125026347226,203778264789'   # Comma-separated GCP folder numeric IDs
  project_ids: 'my-project-1,my-project-2' # Comma-separated GCP project IDs
  exclude_tags: '' # Optional: omit if not filtering resources by label
  include_tags: '' # Optional: omit if not filtering resources by label

After the agent starts, discovered projects and their resources appear in the Instana UI under Infrastructure within the first poll cycle.

GCP folders can contain child folders and projects. When you configure folder_ids, the agent discovers all projects by traversing the folder hierarchy recursively, up to 3 levels of nesting from each configured root folder. Projects and folders beyond that depth are not discovered automatically and must be added directly to project_ids or folder_ids to include them.

You can override the global folder_ids and project_ids settings for individual GCP sensors. Each property is overridden independently. For example, a sensor-specific project_ids setting overrides only the global project_ids value and does not affect the global folder_ids value. Duplicate projects are removed automatically.

# Global configuration — applies to all GCP sensors unless overridden
com.instana.plugin.gcp:
  credentials_path: '/opt/instana/credentials/cred-gcp.json'
  folder_ids: '125026347226,203778264789'
  project_ids: 'my-project-1,my-project-2'

# Per-sensor override — Cloud SQL uses its own project_ids
# The global folder_ids ('125026347226,203778264789') still applies to Cloud SQL
com.instana.plugin.gcp.sql:
  credentials_path: '/opt/instana/credentials/cred-gcp.json'
  project_ids: 'sql-prod-project-1,sql-prod-project-2'

The following table lists the plugin configuration name for each GCP sensor:

• Use project_ids for precise scope: If you know exactly which projects to monitor, configure them directly in project_ids. This approach prevents newly added projects within a folder from being included automatically.
• Ensure billing and APIs are enabled: All monitored projects must have billing enabled and the Cloud Monitoring API activated. Projects that do not meet these requirements do not return metrics. For more information, see Required GCP service API.

The include_tags and exclude_tags fields filter individual GCP resources within a project based on their GCP labels. For example, use these fields to monitor only resources labeled env:prod or to exclude resources labeled env:dev.

These fields apply only at the resource level and cannot be used to filter which projects or folders are monitored. To monitor a specific set of projects, configure those project IDs directly in project_ids instead of relying on folder discovery.

The following observations outline the validated performance limits for the Instana agent when monitoring GCP resources. These results are based on load testing with 50 GCP projects (~1,200 total service instances) on a GCE e2-small instance (2 vCPUs, 2 GB RAM) with the default agent heap of 160 MB, sustained over a 24-hour period.