Try it free

Create a GCP connection (Preview)

  • Latest Dynatrace
  • How-to guide
  • Preview

Prerequisites

Before creating a Google Cloud connection, ensure you have completed the following prerequisites.

1. Dynatrace

Without the Dynatrace IAM permissions below, you can't open the New connection wizard or complete the setup.

Create an IAM user with appropriate permissions

  1. Create a CloudsAdmins group (if it doesn't already exist).
  2. Select Permissions > Scope and add the following policies:
    • Data-Acquisition Cloud Integrations All
    • Standard User
  3. Set scope to Account-Wide or Environment-Wide, then select Save.
  4. Verify that the CloudsAdmins group Permissions section shows both policies.
  5. Add your IAM user as a member of the CloudsAdmins group.

2. Google Cloud

  1. You need a Google Cloud project where the monitoring service account will be created, and sufficient IAM permissions to configure the integration.

The roles below apply to the principal running setup—yourself in Manual mode, or the principal that executes Terraform in Automated via Terraform mode. They are not granted to the monitoring service account itself. In Automated via Terraform mode, Terraform creates the service account, assigns its viewer roles, and grants the Dynatrace principal impersonation rights for you.

TaskRequired roleScope

Create service account

roles/iam.serviceAccountAdmin

Service account project

Enable APIs

roles/serviceusage.serviceUsageAdmin

Service account project

Grant Dynatrace impersonation rights

roles/iam.serviceAccountAdmin

Service account project

Store Terraform state (if using GCS)

roles/storage.objectUser

State bucket project

Grant monitoring access to projects

roles/resourcemanager.projectIamAdmin

Each monitored project

Grant monitoring access to folders

roles/resourcemanager.folderIamAdmin

Each monitored folder

Grant monitoring access to organization

roles/resourcemanager.organizationIamAdmin

Organization

If you have roles/owner on the relevant projects, folders, or organization, you already have sufficient permissions.

  1. If your organization uses domain-restricted sharing your Google Cloud organization may restrict which external identities can be granted IAM roles. This is controlled by the iam.allowedPolicyMemberDomains organization policy. If enabled, you'll need to add the Dynatrace customer identity to your allowed list before Dynatrace can connect. The Dynatrace identity is C03cngnp6.

3. Tooling

  1. Install and configure the Dynatrace CLI (dtctl). After the wizard creates a connection, you need dtctl to link the service account and enable monitoring.
  2. If you chose Automated via Terraform as your deployment method, install Terraform.

Limitations

  • If you want to have more than 100 Google Cloud connections, contact your account team to request a quota increase. The limit will increase when the feature reaches general availability.
  • Each Google Cloud service account supports only one connection. Reusing the same service account across multiple connections causes duplicate data ingestion.

Best practices

  • We do not recommned monitoring more than 15,000 resources through a single Google Cloud Service Account.

  • Do not monitor more than 375 Google Cloud projects via a scoping project as this violates Google Cloud best practices.

  • Group projects by monitoring requirements under a single service account—one service account can oversee many projects and is managed through a single monitoring configuration—simpler to operate but applies the same metric selection, filters, and enrichment to all projects it covers.

    If projects have different monitoring requirements, use separate service accounts so each can be paired with its own monitoring configuration. Prefer more service accounts over fewer for maximum flexibility.

View Google Cloud connections

Go to Settings Settings > Collect and capture > Cloud and virtualization > Google Cloud (Preview).

The connections list displays all configured Google Cloud connections.

Connection list columns

  • Use the Filter all columns field to search connections.
  • Select to display Column settings.
  • Select Refresh to reload the list.
  • Select New connection to create a new connection.
ColumnDescription

Name

Connection name

Status

Health status (Pending/Healthy/Unhealthy)

Service Account Email

The Google Cloud service account used for this connection

Monitored Projects

Number of projects being monitored

Metric Collection Scope

All or Scoping

Created by

User who created the connection

Last modified

Date of last configuration change

Created

Connection creation date

Create a new Google Cloud connection

1. Select connection model

  1. Enter a friendly connection name that is unique (for example, MyEastProd3Account).

  2. Choose the Deployment method.

OptionDescription

Automated via Terraform Recommended

Deploy and configure Google Cloud resources automatically using Terraform for consistent, repeatable setups.

Manual

Set up Google Cloud resources directly through the console, CLI, or your own Infrastructure-as-Code tooling. Use this if you already have existing deployment processes.

  1. In Monitoring service account:

    • Copy the Dynatrace principal—–this is the Dynatrace identity used as "Service Account Token Creator" for your service account. You'll need it when granting impersonation rights in Google Cloud.
    • Enter a Service account name (for example, dynatrace-monitoring).
    • Enter the Project ID of the Google Cloud project where the service account will be created.

  2. Select Next.

2. Select monitoring configuration options

You can modify the observability settings after the connection is created.

Configuration mode

ModeIncludes

Recommended

  • Cloud inventory and topology
  • Common Google Cloud services (Google products) and recommended Cloud Monitoring metrics
  • Google Cloud logs
  • Google Cloud folder and project filters

Advanced

  • Everything in Recommended
  • Google Cloud folder, project, label- and tag-based filters
  • Google Cloud label and tag enrichment

Deployment location

Log forwarding and asset inventory feed deployment location: Select a single Google Cloud region where forwarding infrastructure will be deployed (for example, us-central1).

Metric collection scope

Choose whether to collect metrics from all connected projects or only Scoping projects.

OptionDescription

All

Collect metrics from all projects visible to the connection

Scoping

Collect metrics only from metric scoping projects

When choosing Scoping, Dynatrace polls metrics only from scoping projects. Folder and project filters apply.

Scoping projects list

By default, Dynatrace automatically detects which projects are scoping projects. Detection results are cached, so changes to your Google Cloud monitoring scopes may take some time to reflect in Dynatrace. You can optionally provide an explicit list of scoping project IDs.

When specified, Dynatrace uses your list directly instead of auto-detection, which ensures immediate accuracy and avoids detection overhead in environments with many projects.

Scoping project IDs: Enter the project IDs of your scoping projects (for example, my-scoping-project-1, my-scoping-project-2).

Asset feed scope

Choose the scope from which asset feed events are ingested: Organization, Folders (default—enter folder IDs), or Projects.

When you select the Advanced configuration mode, the following additional configuration options appear.

Location filters

Toggle on to restrict topology and metrics polling to specific locations.

Google Cloud Monitor metrics

The service list shows all supported Google Cloud products. For each service:

  • Toggle on/off to turn on/off metric collection

  • Select a Metric collection set

    ModeDescription

    Recommended

    Ingest Dynatrace-recommended metrics for this service

    Recommended + custom

    Recommended metrics + additional service-related metrics you specify

    Auto-discovery

    Ingest all available metrics for this service

Best practice

Auto-discovery is not meant for long-term use. Use it to explore what metrics are available, then select only the metrics relevant to your use case. This helps you to keep Dynatrace and Google Cloud costs low.

  • Available services include: Cloud Storage, Cloud SQL, Cloud Run, Compute Engine, Kubernetes Engine, BigQuery, and others.

    See Supported services for the full list.

  • Use Search services to filter the list.

  • Use Show all dropdown to filter by enabled/disabled status.

  • Select Reset to default to restore default selections.

Additional metrics (per service)

When using Recommended + custom, select Add metric to specify additional metrics:

FieldDescription

Monitored resource type

The Google Cloud resource type (for example, gcs_bucket)

Metric type

The full metric path (for example, storage.googleapis.com/anywhere_cache/ingested_bytes_count)

Metric labels

Labels to include (for example, cache_zone)

Exclude metric prefixes (Auto-discovery)

When using Auto-discovery, specify metric prefixes to exclude. Use * as a wildcard (for example, storage.googleapis.com*).

Advanced settings: Ingest any Google Cloud Monitor metrics

  1. Turn on the toggle to ingest metrics not tied to a specific service or not yet supported by Dynatrace.

  2. Select + Add metric and provide:

    • Monitored resource type
    • Metric type
    • Metric labels

Folder filters

Turn on the toggle to monitor projects within specific Google Cloud folders only. All folders are monitored by default. This works similarly to the project filter.

  • Enter folder IDs: Numeric folder IDs (for example, 178078973866, 178078973869).
Project filters

Turn on the toggle to monitor only specific projects. All projects are monitored by default unless excluded by a project filter.

  • Enter project IDs: Specify Google Cloud project IDs to monitor (for example, google-cloud-project-name-1, google-cloud-project-name-2).
Label- and tag-based filters

Turn on the toggle to filter monitored resources based on their Google Cloud labels or tags. Use this to include or exclude specific resources from monitoring.

  • Included filters: Only resources matching these filters are monitored.

    • Label-based: Enter label key-value pairs (for example, environment:production).
    • Tag-based: Enter tag IDs (for example, tagKeys/123456789/tagValues/987654321 or project/environment/production).

  • Excluded filters: Resources matching these filters are excluded from monitoring.

    • Label-based: Enter label key-value pairs to exclude (for example, environment:development).
    • Tag-based: Enter tag IDs to exclude.

Use include filters to monitor only specific workloads (for example, production environments). Use exclude filters to skip resources you don't need to monitor (for example, development or test environments).

Unexpected-data tagging

Preview limitation

The unexpected-data tagging feature is not yet available.

Turn on the toggle to tag streamed data (logs, asset inventory events) that doesn't match your filters. Use this to identify mismatches and either drop data in OpenPipeline or adjust your Google Cloud configuration.

Data will be tagged with the attribute: da.unexpected.

Label and tag enrichment

Forward selected labels and tags from Google Cloud assets to their associated observability signals.

  • Google Cloud labels: Enter label keys to forward (for example, team).
  • Google Cloud tags: Enter tag IDs to forward (for example, payroll/app).

Resulting attribute names:

SourceExample inputAttribute name

Label

team

gcp.labels.team

Tag

payroll/app

gcp.tags.payroll.app

Dynatrace attribute enrichment

  1. Map Google Cloud labels or tags to Dynatrace attributes. Each attribute can be set using:

  • Google Cloud label: Use the value of a specific label

  • Google Cloud tag: Use the value of a specific tag

  • Custom value (literal): Use a static string value

    AttributeDescription

    Enable security context

    Maps to dt.security_context. Enriches signals and entities.

    Enable cost allocation (Cost center)

    Maps to dt.cost.costcenter. Enriches signals and entities.

    Enable cost allocation (Product)

    Maps to dt.cost.product. Enriches signals and entities.

  • Select Next.

3. Deploy in Google Cloud

This step differs based on your deployment method.

Configure Dynatrace tokens

  1. Generate a Settings token to authenticate dtctl, with the following permissions:
  • settings:objects:read
  • settings:objects:write
  • extensions:configurations:read
  • extensions:configurations:write
  • If you plan to enable log forwarding (logs_enabled = true in terraform.tfvars), also generate a Log Ingest token with:
  • logs.ingest
  • Select Generate for each token. Select to copy the token value. Select to reveal the token.

Deploy Terraform in Google Cloud

  1. Select Download Terraform to download the pre-configured Terraform bundle (a .zip file). The bundle contains:

    FileDescription

    .tf files

    Terraform configuration that creates the monitoring service account, enables required APIs, grants viewer roles, and grants the Dynatrace principal impersonation rights.

    config.auto.tfvars

    Wizard-generated variables (such as project_id, service_account_id, and dt_service_account_email). Auto-loaded by Terraform; leave it as-is.

    terraform.sample.tfvars

    The file you edit to choose the monitoring scope.

    README.md

    Bundled quick-reference.

    When applied, Terraform will:

    • Enable compute.googleapis.com, cloudresourcemanager.googleapis.com, cloudasset.googleapis.com, and monitoring.googleapis.com on the service account project.
    • Create the monitoring service account.
    • Grant roles/viewer on each listed project, roles/resourcemanager.folderViewer on each listed folder, and roles/resourcemanager.organizationViewer on each listed organization.
    • Grant the Dynatrace principal roles/iam.serviceAccountTokenCreator on the new service account (impersonation trust).

    roles/viewer is a broad predefined role that some organizations restrict. If your organization requires more granular permissions, see the Grant permissions to the service account section in Manual onboarding reference for the exact list of IAM permissions Dynatrace needs to create a custom role.

  2. Make sure your environment is ready:

    • Terraform is installed.
    • You're authenticated against the service account project—for example, with gcloud auth application-default login.

  3. Extract the bundle. Rename terraform.sample.tfvars to terraform.tfvars and fill in the values:

    VariableRequiredDescriptionExample

    region

    Optional

    Region for created resources. Defaults to us-central1.

    "us-central1"

    project_ids_for_monitoring

    Required 1

    Project IDs to grant the service account roles/viewer.

    ["project-1", "project-2"]

    folder_ids_for_monitoring

    Required 1

    Folder IDs to grant the service account roles/resourcemanager.folderViewer.

    ["folders/123456789012"]

    organization_ids_for_monitoring

    Required 1

    Organization IDs to grant the service account roles/resourcemanager.organizationViewer.

    ["organizations/123456789012"]

    1

    At least one of the three scope lists must be non-empty. Otherwise the service account has no resources to read.

  4. From the bundle directory, run:

    terraform init
    terraform plan
    terraform apply

    Alternatively, apply the bundle through Google Cloud Infrastructure Manager or any other Terraform runner.

  5. In Activation, select one of the following:

    • Terraform has been deployed: You ran Terraform yourself and the wizard is still open. Select this to finalize the connection creation.

      It may take up to 5 minutes for the new service account to become available in Google Cloud. If finalization doesn't complete, use the dtctl steps below.

    • Terraform will be deployed later: Someone else is running Terraform, or you need to close the wizard. Share the downloaded Terraform scripts and this documentation link with the person who has the required Google Cloud permissions. Once Terraform deployment is complete, finalize the connection manually using the dtctl steps below.

  6. After Terraform deployment is complete, authenticate dtctl to your Dynatrace environment. Pick one of the following options.

    • Recommended Browser-based OAuth login

      dtctl auth login \
        --context my-env \
        --environment https://<tenant>.apps.dynatrace.com

    • Platform token (headless/scripted)

      Use the settings token you generated earlier (not the log ingest token).

      dtctl config set-context my-env \
        --environment https://<tenant>.apps.dynatrace.com \
        --token-ref my-token
      

      dtctl config set-credentials my-token --token <settings-token-from-step-above>
      

      dtctl config use-context my-env

  7. Link the service account to the connection and enable monitoring:

    dtctl enable gcp monitoring \
      --name "<configuration-name>" \
      --serviceAccountId "<service-account-email>"

    In the Dynatrace UI, this command is displayed with <configuration-name> and <service-account-email> already filled in with the real values for your connection—copy it from the wizard rather than typing it by hand.

    Future perspective

    Terraform will finalize the connection automatically. For now, proceed with dtctl.

  8. Optional See Manual onboarding reference for step-by-step instructions.

  9. Select Finish to complete the wizard. The connection is created and appears in the connections list.

In manual mode, you have decided to configure Google Cloud yourself. This includes:

Which steps to run

This wizard handles the Dynatrace configuration (steps 1, 6, and 7 in the Manual onboarding reference).

You only need to complete the Google Cloud steps:

  • Required 2–5
  • Optional 9–10 for asset inventory feed and log forwarding

  1. Enable required Google Cloud APIs.

  2. Create a service account for Dynatrace to use.

  3. Grant permissions to the service account at project, folder, or organization level.

  4. Establish trust between Dynatrace and your service account.

  5. Optional Deploy log and asset inventory feed forwarders.

    For step-by-step instructions using gcloud CLI and dtctl, see Manual onboarding reference.

  6. On the final page, enter your Service account email, select the acknowledgement checkbox, and select Finish. The connection is created and appears in the connections list.

Next steps

Once you select Finish, the connection is created in Dynatrace. However, data collection doesn't start until either:

  • Terraform deployment is complete and the connection is finalized with dtctl (if using Automated via Terraform mode)
  • Manual configuration is complete (if using Manual mode)

After the Google Cloud side is configured:

  • Dynatrace begins polling for topology data immediately.
  • Metrics collection starts within the next five-minute polling interval.
  • The connection status changes from Pending to Healthy once Dynatrace successfully authenticates.

You can monitor the deployment progress in the connection's Health tab.

Related tags
Infrastructure Observability