Create GCP connection via Terraform

Latest Dynatrace
How-to guide

Configure both the Dynatrace side and all Google Cloud resources using Terraform — no wizard or manual CLI steps required. This method is suitable for teams that manage infrastructure as code and want a fully automated, repeatable setup.

Terraform scope

Terraform manages the Google Cloud resources (service account, IAM bindings, APIs, Pub/Sub topics, Dataflow jobs, asset feeds) and the Dynatrace connection. By default, Terraform also creates the monitoring configuration (metrics, filters, enrichment) from the mconfig_value payload in your terraform.tfvars. If you already created a monitoring configuration in the Settings app or with dtctl, you can set its ID in mconfig_id instead. Terraform then enables the existing configuration and keeps its settings.

Prerequisites

Before you begin:

Terraform version 1.7 or later is installed.
You have a Dynatrace SaaS environment.
You have a Google Cloud project where the monitoring service account will be created (the service account project).
The user running Terraform is authenticated against the service account project and has these roles on it:
- roles/iam.serviceAccountAdmin, roles/iam.serviceAccountUser, roles/serviceusage.serviceUsageAdmin, roles/storage.objectUser, roles/resourcemanager.projectIamAdmin, roles/pubsub.admin, roles/cloudasset.owner — always required.
- roles/resourcemanager.folderIamAdmin — when monitoring folders.
- roles/resourcemanager.organizationIamAdmin — when monitoring organizations.
- roles/dataflow.admin, roles/logging.admin — when logs_enabled = true.
A Dynatrace API token with settings:objects:read, settings:objects:write, extensions:configurations:read, and extensions:configurations:write scopes (the settings token).
A Dynatrace token with the data-acquisition:logs:ingest scope (the Log Ingest token) — only when logs_enabled = true.

Step 1: Download the Terraform bundle

Download the latest release from dynatrace-gcp-deployment-template and extract it to your working directory.

The bundle contains:

File	Purpose
`.tf` files	Terraform configuration that creates the monitoring service account, enables required APIs, grants IAM roles, grants the Dynatrace principal impersonation rights, creates the Dynatrace connection, and creates (or imports) and enables the monitoring configuration. Optionally, it also creates the asset feed.
`modules/logs/`	Terraform module for the optional log forwarding pipeline (Pub/Sub, Cloud Storage buckets, Secret Manager secret, and Dataflow job). It doesn't create log sinks.
`terraform.tfvars`	Your environment-specific variable values, including the monitoring configuration payload (`mconfig_value`). Fill this in before running Terraform.
`README.md`	Bundled quick-reference.

Step 2: Configure your variables

Edit terraform.tfvars and fill in your environment values:

# Dynatrace environment
tenant_id = "<your-environment-id>"

# GCP project where the monitoring service account is created
project_id         = "<your-service-account-project-id>"
service_account_id = "dynatrace-monitoring"

# Monitoring scope — add project, folder, or organization IDs to monitor
project_ids_for_monitoring      = ["project-a", "project-b"]
folder_ids_for_monitoring       = []
organization_ids_for_monitoring = []

# GCP region for infrastructure (Dataflow, Pub/Sub)
region = "us-central1"

# Optional features
logs_enabled       = false
asset_feed_enabled = false

# Monitoring configuration payload (Terraform creates the configuration from it)
mconfig_value = <<-JSON
  {
    "version": "2.0.3",
    "description": "GCP monitoring",
    "featureSets": ["cloud_run_essential", "cloud_storage_essential"],
    "googleCloud": {
      "credentials": [{ "description": "GCP monitoring" }],
      "locationFiltering": [],
      "projectFiltering": [],
      "folderFiltering": [],
      "labelEnrichment": [],
      "tagEnrichment": []
    }
  }
  JSON

The example payload is shortened. Start from the complete mconfig_value in the bundle's terraform.tfvars.

The following table describes the main variables:

Variable	Required	Description
`tenant_id`	Required	Your Dynatrace environment ID. Terraform derives the environment URL (`https://<tenant_id>.apps.dynatrace.com`) from it.
`project_id`	Required	Service account project. Terraform creates the service account, Pub/Sub topics, and Dataflow job here.
`service_account_id`	Required	Short ID of the monitoring service account, without the `@<project>.iam.gserviceaccount.com` suffix.
`project_ids_for_monitoring`, `folder_ids_for_monitoring`, `organization_ids_for_monitoring`	At least one non-empty	Scopes to monitor. Folder IDs use the form `folders/123456789012`. Terraform grants the viewer roles at each scope.
`mconfig_value`	Used when `mconfig_id` is empty	Full monitoring configuration as a JSON string: feature sets, location, project, and folder filtering, label and tag filtering and enrichment, and custom resources. Terraform sets the credentials (connection and service account) and enables the configuration. For all properties, see Monitoring configuration reference.
`mconfig_id`	Optional	ID of an existing monitoring configuration (a lowercase UUID). When set, Terraform imports and enables that configuration, keeps its settings, and ignores `mconfig_value`. Leave it empty to let Terraform create a new configuration.
`region`	Optional	Region for created resources. Defaults to `us-central1`.
`logs_enabled`	Optional	Set to `true` to deploy the log forwarding pipeline. Defaults to `false`.
`asset_feed_enabled`	Optional	Set to `true` to deploy the asset feed. By default, the feed covers the same projects, folders, and organizations you monitor. To target different scopes, set `project_ids_for_asset_feed`, `folder_ids_for_asset_feed`, or `organization_ids_for_asset_feed`. Avoid overlapping scopes, because they produce duplicate events and increase cost. Use `asset_feed_asset_types` to change the asset types that trigger change events.
`custom_labels`	Optional	Labels applied to every created Google Cloud resource, in addition to the Dynatrace labels. Your values take precedence when keys collide.

Export sensitive values as environment variables — never store them in terraform.tfvars:

# Settings token (settings read/write, extensions read/write) — always required
export TF_VAR_dynatrace_settings_token="<your-dynatrace-settings-token>"

# Log Ingest token — only required if logs_enabled = true
export TF_VAR_dynatrace_api_token="<your-log-ingest-token>"

The Log Ingest token requires the data-acquisition:logs:ingest scope. Create a platform token if you don't have one. If logs_enabled = false, you can omit the Log Ingest token. If logs_enabled = true and the token is empty, terraform plan fails with an error.

Step 3: Configure state storage

Terraform state tracks the resources it manages. You are responsible for storing and managing the state file — use your existing backend (GCS, S3, Terraform Cloud, or local storage) according to your organization's practices.

Step 4: Initialize and apply

terraform init
terraform plan
terraform apply

Review the plan output before applying. Terraform will:

Enable cloudresourcemanager.googleapis.com, cloudasset.googleapis.com, monitoring.googleapis.com, pubsub.googleapis.com, and iam.googleapis.com on the service account project. If logs_enabled = true, it also enables logging.googleapis.com, dataflow.googleapis.com, storage.googleapis.com, and secretmanager.googleapis.com.
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 service account (impersonation trust).
Create the Dynatrace GCP connection for the service account.
Create the monitoring configuration from mconfig_value, or, if you set mconfig_id, import the existing configuration. In both cases, link it to the connection and enable it.
If logs_enabled = true: deploy the Pub/Sub topics and subscriptions, Cloud Storage buckets, Secret Manager secret, and Dataflow streaming job. Terraform doesn't create log sinks.
If asset_feed_enabled = true: deploy the Cloud Asset feeds, Pub/Sub topic, and push subscription.

Terraform enables the APIs on the service account project only. Each monitored project needs monitoring.googleapis.com enabled.

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 (constraints/iam.allowedPolicyMemberDomains), add the Dynatrace principal to your allowed list before applying. The identity is specific to your environment — retrieve it via dtctl get gcp connection principal or from the Settings app wizard.

Step 5: Create log sinks Optional

If you set logs_enabled = true, Terraform deployed the log forwarding pipeline but no log sinks. Create a project-level log sink in each project whose logs you want to forward, and point it at the Pub/Sub topic in the service account project. No logs reach Dynatrace until you do. For the commands, see Create log sinks.

What's next?

Allow up to 5 minutes for the connection to become Healthy in Dynatrace.
Metrics appear within the first 5-minute polling interval after the connection is healthy, plus Google's metric ingest delay.
Topology appears within about 15 minutes after the connection is healthy. After that, Dynatrace works from asset feed events (if you enabled the asset feed) and runs a full scrape every hour.
To update the connection after initial setup, see Manage GCP connections via Terraform.