Only a Dynatrace account administrator and a Google Cloud administrator can successfully complete the initial prerequisites.
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:
serviceusage.services.enable)iam.serviceAccounts.create) on the service account projectresourcemanager.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.
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:
In this documentation section context:
A built-in user with View and manage users and groups permission.
A customer-created custom IAM group whose members can create and manage Google Cloud connections in
Settings.
An IAM user, member of the CloudsAdmins group. The name is used here solely for context; any Dynatrace IAM user can be used.
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.
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.
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 AllStandard UserAssign your CloudAdmin IAM user (or any other Dynatrace IAM user) as a member of the CloudsAdmins group.
Before you start onboarding, make sure all prerequisites are completed.
CloudsAdmins IAM group) and open If the button is grayed out, it means you do not have the proper permissions to create a connection. Please, contact your administrator.
Enter a friendly connection name that is unique (for example, MyEastProd3Account).
Choose a Deployment method.
| Option | Description |
|---|---|
| Automated via Terraform | Deploy and configure Google Cloud resources automatically using Terraform for consistent, repeatable setups. Recommended for new setups. |
| Manual | Set up Google Cloud resources directly using the gcloud CLI. Use this if you have existing deployment processes or want full control. |
In Monitoring service account:
dynatrace-monitoring).Select Next.
You can modify the observability settings after the connection is created.
Recommended monitors your Google Cloud environment using Dynatrace's default settings. Advanced monitors it using your own customized settings.
| Mode | Includes |
|---|---|
| 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 |
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.
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.
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.
Choose whether to collect metrics from all visible projects or only Scoping projects.
| Option | Description |
|---|---|
| All | Collect metrics from all projects visible to the connection |
| Scoping | Collect 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.
Toggle on to restrict topology and metrics polling to specific locations.
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
| Mode | Description |
|---|---|
| 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 |
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.
When using Recommended + custom, select Add metric to specify additional metrics:
| Field | Description |
|---|---|
| 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) |
When using Auto-discovery, specify metric prefixes to exclude. Use * as a wildcard (for example, storage.googleapis.com*).
Turn on the toggle to ingest metrics not tied to a specific service or not yet supported by Dynatrace.
Select + Add metric and provide:
Turn on the toggle to monitor projects within specific Google Cloud folders only. All folders are monitored by default.
178078973866, 178078973869).Turn on the toggle to monitor only specific projects. All projects are monitored by default unless excluded by a project filter.
google-cloud-project-name-1, google-cloud-project-name-2).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.
environment=production).myproject/environment=production).Excluded filters: Resources matching these filters are excluded from monitoring.
environment=development).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.
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.
team).payroll/app).Resulting attribute names:
| Source | Example input | Attribute name |
|---|---|---|
| Label | team | gcp.labels.team |
| Tag | payroll/app | gcp.tags.payroll.app |
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.
Generate the tokens required to connect Dynatrace to your Google Cloud environment:
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:objects:read, settings:objects:write, extensions:configurations:read, extensions:configurations:writedata-acquisition:logs:ingestIf log forwarding is turned on and the ingest token variable is empty, terraform plan fails with an error.
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.
Select Download Terraform to download the pre-configured Terraform bundle (a .zip file). The bundle contains:
| File | Description |
|---|---|
.tf files | Terraform 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.tfvars | Wizard-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.tfvars | Deployment 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.md | Bundled quick-reference. |
When applied, Terraform will:
cloudresourcemanager.googleapis.com, cloudasset.googleapis.com, monitoring.googleapis.com, pubsub.googleapis.com, and iam.googleapis.com on the service account project.roles/monitoring.viewer, roles/cloudasset.viewer, and roles/browser on each listed project, folder, and organization.roles/iam.serviceAccountTokenCreator on the new service account (impersonation trust).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.
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:
| Role | Required when |
|---|---|
roles/iam.serviceAccountAdmin | Always |
roles/iam.serviceAccountUser | Always |
roles/serviceusage.serviceUsageAdmin | Always |
roles/storage.objectUser | Always |
roles/resourcemanager.projectIamAdmin | Always |
roles/resourcemanager.folderIamAdmin | Monitoring folders |
roles/resourcemanager.organizationIamAdmin | Monitoring organizations |
roles/pubsub.admin | Always |
roles/cloudasset.owner | Always |
roles/dataflow.admin | logs_enabled = true |
roles/logging.admin | logs_enabled = true |
Extract the bundle and open terraform.tfvars. It comes pre-filled with your wizard selections — review and adjust the values:
| Variable | Required | Description | Example |
|---|---|---|---|
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/monitoring.viewer, roles/cloudasset.viewer, and roles/browser. | ["project-1", "project-2"] |
folder_ids_for_monitoring | Required 1 | Folder 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_monitoring | Required 1 | Organization 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"] |
At least one of the three scope lists must be non-empty. Otherwise the service account has no resources to read.
Before running terraform apply, review terraform.tfvars carefully. The wizard pre-fills it based on your selections — confirm each value fits your environment:
asset_feed_enabled) and log forwarding (logs_enabled).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.
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 initterraform planterraform 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.
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.
Select Finish to complete the wizard. The connection is created and appears in the connections list.
Once you select Finish, the connection is created in Dynatrace. After Google Cloud configuration is complete:
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.