Try it free

Create a GCP connection via Settings app

  • Latest Dynatrace
  • How-to guide

Prerequisites

Only a Dynatrace account administrator and a Google Cloud administrator can successfully complete the initial prerequisites.

Google Cloud

Actions in this section must be performed by a Google Cloud administrator with appropriate permissions.

The Google Cloud identity you use to run the setup (either Terraform apply or manual gcloud commands) needs:

  • Permission to enable APIs on the service account project (serviceusage.services.enable)
  • Permission to create service accounts (iam.serviceAccounts.create) on the service account project
  • Permission to grant IAM roles on each monitored project, folder, or organization (typically requires resourcemanager.projects.setIamPolicy, resourcemanager.folders.setIamPolicy, or resourcemanager.organizations.setIamPolicy)

In environments where full duty separation is practiced, we recommend that the Dynatrace administrator share the Terraform bundle with the platform team or Google Cloud administrators.

Dynatrace

Actions in this section must be performed by a Dynatrace administrator with appropriate permissions.

GCP Cloud Platform Monitoring is integrated with the core Dynatrace Identity and Access Management (IAM) design.

Learn more about the basic concepts:

  • Users, service users
  • Local groups, policies
  • Platform tokens for service users

Create the Dynatrace IAM baseline

In this documentation section context:

Dynatrace account admin

A built-in user with View and manage users and groups permission.

CloudsAdmins

A customer-created custom IAM group whose members can create and manage Google Cloud connections in Settings Settings.

CloudAdmin

An IAM user, member of the CloudsAdmins group. The name is used here solely for context; any Dynatrace IAM user can be used.

Data-Acquisition Cloud Integrations All

A Dynatrace-created built-in IAM policy that contains all the (least privilege) permission scopes required to support the creation and management of multi-cloud (AWS/Azure/GCP) connections from Settings Settings.

Interactive IAM identity (IAM user)

If you just created a new Dynatrace Account with a trial environment, you can skip steps 1 and 2, as your IAM user is considered an Admin. When the Account and its associated environments are heading toward production, we recommend that you follow the IAM best practices below.

  1. Create the CloudsAdmins group.

    Once the CloudsAdmins group is created, select Permissions > Scope and add the Data-Acquisition Cloud Integrations All and Standard User policies.

    Apply Account-Wide or Environment-Wide, then select Save.

    Validate: The CloudsAdmins Permissions section should show:

    • Data-Acquisition Cloud Integrations All
    • Standard User
  2. Assign your CloudAdmin IAM user (or any other Dynatrace IAM user) as a member of the CloudsAdmins group.

Onboarding

Before you start onboarding, make sure all prerequisites are completed.

  1. Log in to Dynatrace as the IAM user (member of the CloudsAdmins IAM group) and open Settings Settings.
  2. Go to Collect and capture > Cloud and virtualization > Google Cloud and select New connection.

If the button is grayed out, it means you do not have the proper permissions to create a connection. Please, contact your administrator.

Step 1: Select connection model

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

  2. Choose a Deployment method.

    OptionDescription
    Automated via TerraformDeploy and configure Google Cloud resources automatically using Terraform for consistent, repeatable setups. Recommended for new setups.
    ManualSet up Google Cloud resources directly using the gcloud CLI. Use this if you have existing deployment processes or want full control.
  3. In Monitoring service account:

    1. 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.
    2. Enter a Service account name (for example, dynatrace-monitoring).
    3. Enter the Project ID of the Google Cloud project where the service account will be created.
  4. Select Next.

Step 2: Select monitoring configuration options

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

Configuration mode

Recommended monitors your Google Cloud environment using Dynatrace's default settings. Advanced monitors it using your own customized settings.

ModeIncludes
RecommendedCloud inventory and topology
Common Google Cloud services (Google products) and recommended Cloud Monitoring metrics
Google Cloud logs
Google Cloud folder and project filters
AdvancedEverything in Recommended
Google Cloud folder, project, label- and tag-based filters
Google Cloud label and tag enrichment

Deployment location

Log forwarding deployment location: Select a single Google Cloud region where the log-forwarding Dataflow job and its Cloud Storage buckets are deployed (for example, us-central1). The region applies only when log forwarding is turned on. It doesn't apply to the asset feed.

Logs

Turn on the Logs toggle to forward Google Cloud logs to Dynatrace. This requires log-forwarding infrastructure (Pub/Sub and a Dataflow streaming job) in the deployment location above; the Terraform bundle deploys it, or you deploy it manually with the gcloud CLI. You then create a log sink in each project whose logs you want to forward. Terraform doesn't create sinks. Leave the toggle off if you only want topology and metrics.

Asset feed

Turn on the Asset feed toggle to stream near-real-time resource-change events from Google Cloud Asset Inventory (a Pub/Sub push feed) so topology updates without waiting for the next poll. When off, topology is still discovered through periodic polling, just less frequently. Enabling it deploys Cloud Asset feeds for your monitoring scope, and a Pub/Sub topic and push subscription in the service account project. Pub/Sub topics and subscriptions aren't tied to a region, so the deployment location doesn't apply to the asset feed.

Metric collection scope

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

OptionDescription
AllCollect metrics from all projects visible to the connection
ScopingCollect metrics only from metric scoping projects (GCP projects whose metrics scope includes other projects)

When you choose Scoping, Dynatrace polls metrics only from scoping projects. Dynatrace detects scoping projects automatically, and you can't specify them manually. Folder and project filters apply.

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
    RecommendedIngest Dynatrace-recommended metrics for this service
    Recommended + customRecommended metrics + additional service-related metrics you specify
    Auto-discoveryIngest 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 typeThe Google Cloud resource type (for example, gcs_bucket)
Metric typeThe full metric path (for example, storage.googleapis.com/anywhere_cache/ingested_bytes_count)
Metric labelsLabels 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.

  • 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, myproject/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).

Exclude filters are always applied after include filters. If a resource matches both, it is excluded from monitoring.

Label and tag enrichment

Per-connection enrichment configuration is a first step. This concept will evolve into a platform-central enrichment config, where enrichment rules are defined once and applied across all connections.

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
Labelteamgcp.labels.team
Tagpayroll/appgcp.tags.payroll.app

Dynatrace attribute enrichment

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

    | Attribute | Description | | :— | :— | | 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.

Step 3: Configure Google Cloud

Configure Dynatrace tokens

Generate the tokens required to connect Dynatrace to your Google Cloud environment:

  • Settings token: Required. Select Generate to create the token.
  • Ingest token: Required only when log forwarding is turned on. Log forwarding is on in the Recommended mode. In the Advanced mode, you can turn it off. Select Generate to create the token.

Select to copy a token value, or select to reveal it. Select Download to save the tokens as files — useful when sharing them with the person deploying the Terraform template.

Neither token is stored in terraform.tfvars. Export the tokens as environment variables before running terraform apply. Export the ingest token only if log forwarding is turned on. If you selected Download, read the values from the downloaded files, where <settings-token-file> and <ingest-token-file> are the file names from your download:

export TF_VAR_dynatrace_settings_token="$(cat <settings-token-file>)"
export TF_VAR_dynatrace_api_token="$(cat <ingest-token-file>)" # only with log forwarding

If you copied the token values instead, set the variables to the copied values.

Required token scopes:

  • Settings token: settings:objects:read, settings:objects:write, extensions:configurations:read, extensions:configurations:write
  • Ingest token: data-acquisition:logs:ingest

If log forwarding is turned on and the ingest token variable is empty, terraform plan fails with an error.

Keep the tokens secret

The tokens are secrets. Don't share them in plain text or commit them to a repository, and delete the downloaded token files when you no longer need them.

Deploy Terraform in Google Cloud

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

    FileDescription
    .tf filesTerraform configuration that creates the monitoring service account, enables required APIs, grants viewer roles, grants the Dynatrace principal impersonation rights, creates the Dynatrace connection, and enables the monitoring configuration.
    config.auto.tfvarsWizard-generated Dynatrace connection settings (such as project_id, service_account_id, tenant_id, and mconfig_id). Auto-loaded by Terraform; leave it as-is.
    terraform.tfvarsDeployment configuration, pre-filled with your wizard selections (monitoring scope, region, and the log forwarding and asset feed toggles). Edit this file to adjust your deployment. The file can also contain mconfig_value. Terraform ignores it, because the wizard already created your monitoring configuration and config.auto.tfvars references it by ID. You control which metrics and services Dynatrace collects in the wizard, and change them later in the Settings app or with dtctl.
    README.mdBundled quick-reference.

    When applied, Terraform will:

    • Enable cloudresourcemanager.googleapis.com, cloudasset.googleapis.com, monitoring.googleapis.com, pubsub.googleapis.com, and iam.googleapis.com on the service account project.
    • Create the monitoring service account.
    • Grant roles/monitoring.viewer, roles/cloudasset.viewer, and roles/browser on each listed project, folder, and organization.
    • Grant the Dynatrace principal roles/iam.serviceAccountTokenCreator on the new service account (impersonation trust).
    • Create the Dynatrace connection for the new service account, link it to the monitoring configuration the wizard created from your selections, and enable that configuration. Terraform keeps the settings of the monitoring configuration and doesn't change them.

    If your organization restricts default-enabled APIs, manually enable monitoring.googleapis.com on each monitored project:

    gcloud services enable monitoring.googleapis.com --project=MONITORED_PROJECT_ID

    If your organization restricts identities by domain, add the Dynatrace principal shown in the wizard as an allowed value in your policy.

    Select How to deploy in Google Cloud for step-by-step deployment guidance.

  2. Make sure your environment is ready:

    • Terraform version 1.7 or later is installed.

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

    • The Google Cloud identity running Terraform has the following roles on the service account project:

      RoleRequired when
      roles/iam.serviceAccountAdminAlways
      roles/iam.serviceAccountUserAlways
      roles/serviceusage.serviceUsageAdminAlways
      roles/storage.objectUserAlways
      roles/resourcemanager.projectIamAdminAlways
      roles/resourcemanager.folderIamAdminMonitoring folders
      roles/resourcemanager.organizationIamAdminMonitoring organizations
      roles/pubsub.adminAlways
      roles/cloudasset.ownerAlways
      roles/dataflow.adminlogs_enabled = true
      roles/logging.adminlogs_enabled = true
  3. Extract the bundle and open terraform.tfvars. It comes pre-filled with your wizard selections — review and adjust the values:

    VariableRequiredDescriptionExample
    regionOptionalRegion for created resources. Defaults to us-central1."us-central1"
    project_ids_for_monitoringRequired 1Project IDs to grant the service account roles/monitoring.viewer, roles/cloudasset.viewer, and roles/browser.["project-1", "project-2"]
    folder_ids_for_monitoringRequired 1Folder IDs to grant the service account roles/monitoring.viewer, roles/cloudasset.viewer, and roles/browser. At folder scope, roles/browser enables listing all projects under the folder.["folders/123456789012"]
    organization_ids_for_monitoringRequired 1Organization IDs to grant the service account roles/monitoring.viewer, roles/cloudasset.viewer, and roles/browser. At organization scope, roles/browser enables listing all folders and projects in the organization.["organizations/123456789012"]
    1

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

    Review before applying

    Before running terraform apply, review terraform.tfvars carefully. The wizard pre-fills it based on your selections — confirm each value fits your environment:

    • Confirm the list of project, folder, or organization IDs to monitor.
    • Decide whether to enable the asset inventory feed (asset_feed_enabled) and log forwarding (logs_enabled).
    • Review the default asset types for the feed (asset_feed_asset_types) — all asset types are discovered via the hourly snapshot regardless of this setting. This list controls which types also receive near-realtime change events outside the snapshot. The base set is maintained by Dynatrace; you can extend it with additional GCP resource types your teams rely on.

    See Via gcloud CLI and dtctl for a complete description of all monitoring configuration properties.

  4. From the bundle directory, run:

    Set the environment variables in the same shell session before running these commands. Set the ingest token only if log forwarding is turned on:

    export TF_VAR_dynatrace_settings_token="$(cat <settings-token-file>)"
    export TF_VAR_dynatrace_api_token="$(cat <ingest-token-file>)" # only with log forwarding
    terraform init
    terraform plan
    terraform apply

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

    If you turned on Logs, Terraform deploys the log-forwarding pipeline but no log sinks. Create a log sink in each project whose logs you want to forward. No logs reach Dynatrace until you do.

  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 before the connection status changes to Healthy.

    • 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, the connection finalizes automatically.

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

The wizard handles the Dynatrace configuration for you. You only need to set up the Google Cloud resources manually using the gcloud CLI.

Which steps to run
  • Steps 2–5 from Via gcloud CLI and dtctl: enable APIs, create service account, grant permissions, grant impersonation rights.
  • Steps 9–10 are optional: asset inventory feed and log forwarding.

Skip steps 1, 6, and 7 — the wizard handles those. For step 6 (linking the service account to Dynatrace), enter the service account email in the wizard instead of using dtctl.

Once you've completed the Google Cloud setup, return to the wizard:

  1. Enter your Service account email in the wizard.
  2. Select the acknowledgement checkbox.
  3. Select Finish. The connection is created and appears in the connections list.

What's next?

Once you select Finish, the connection is created in Dynatrace. After Google Cloud configuration is complete:

  • Metrics start flowing within the next five-minute polling interval.
  • GCP topology (resources, relationships) appears within about 15 minutes, once the initial Cloud Asset Inventory scrape completes. After that, changes stream in near real time through the asset inventory feed (if configured), and Dynatrace runs a full scrape every hour.
  • The connection status changes from Pending to Healthy once Dynatrace successfully authenticates.

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

If metrics or topology are still missing after 15 minutes, see Troubleshoot GCP connections.

Related tags
Infrastructure Observability