Migration
This guide covers both bulk and iterative methods of migrating configurations between Dynatrace environments with Dynatrace Configuration as Code via Terraform.
Ensure OneAgent communication is reconfigured via oneagentctl
for migration. Direct OneAgent migration might generate new entity IDs, potentially causing configuration loss.
Improper migration can cause significant environment issues.
Prerequisites
-
Terraform CLI with the Dynatrace provider installed and available under
PATH
. -
Access token with at least the following permissions:
- Read settings (
settings.read
) - Write settings (
settings.write
) - Read configuration (
ReadConfig
) - Write configuration (
WriteConfig
) - Create and read synthetic monitors, locations, and nodes (
ExternalSyntheticIntegration
) - Capture request data (
CaptureRequestData
) - Read credential vault entries (
credentialVault.read
) - Write credential vault entries (
credentialVault.write
) - Read network zones (
networkZones.read
) - Write network zones (
networkZones.write
)
- Read settings (
Certain resources require an OAuth client for authentication (for example, automation, document, and account management APIs). For details, see the resource-specific pages in the Terraform Registry.
Set environment variables
There are two ways to invoke the export utility and subsequent Terraform execution.
Migration methods
There are two main approaches for migration:
-
Bulk—Transfer all configurations from a source to a fresh target environment.
-
Iterative—Transfer configurations by resource group. Ideal for target environments with existing configurations.
For iterative migration, use the Terraform Migration Helper spreadsheet. It aids in tracking migration order and completion.
Bulk migration
Ensure the target environment doesn't have any existing configurations.
Use the -migrate
flag. This will create all of the necessary files with resource dependencies and hardcoded entity IDs.
Windows: terraform-provider-dynatrace.exe -export -migrate
Linux: terraform-provider-dynatrace -export -migrate
To view the resources that are excluded from the default export, run the provider with the -list-exclusions
flag. To export any of the excluded resources, see the Usage Examples.
Iterative migration
The iterative approach is useful for migrating specific resource groups or to environments with existing configurations.
Set environment variables to handle duplicates:
DYNATRACE_DUPLICATE_REJECT=ALL
: Prevents overwriting existing configurations.DYNATRACE_DUPLICATE_HIJACK=ALL
: Allows overwriting existing configurations.
Use the -migrate -datasources
flag. This will create all of the necessary files with dependencies via data sources and hardcoded entity IDs.
Windows: terraform-provider-dynatrace.exe -export -migrate -datasources <resourcename>
Linux: terraform-provider-dynatrace -export -migrate -datasources <resourcename>
Troubleshooting
Some resources might fail during migration. Common issues include:
- Some API endpoints might reject outdated configurations. For instance, calculated service metrics now require a management zone or a condition marked with service property.
- Some API endpoints validate whether entity IDs in the configuration exist. If missing in the target environment, re-apply once the entities are present.
If you experience any other errors, please create a GitHub issue.