Module 2 du parcours Terraform Dynatrace SaaS : l’import Terraform Dynatrace SaaS permet de reprendre sous contrôle du code une configuration créée à la main dans l’interface.
Parcours : Terraform Dynatrace SaaS · Module 2/3 · Durée : ~45 min · Niveau : Intermédiaire
Objectifs :
- Exporter une configuration existante au format HCL avec l’utilitaire du provider
- Importer les ressources exportées dans l’état Terraform
- Détecter la dérive entre l’état, le code et l’environnement
- Savoir ce qui est exclu de l’export par défaut
Prérequis : le module 1 (provider installé, authentification SaaS), un environnement SaaS de test et un jeton de plateforme ou un client OAuth. Ce module vaut pour Dynatrace SaaS uniquement.
Dans la plupart des équipes, la configuration existe avant le code : alertes, objectifs de niveau de service (SLO), workflows, créés au fil des incidents. Pour la gérer avec Terraform sans tout réécrire, il faut l’import Terraform Dynatrace SaaS : lire l’existant, le transformer en fichiers .tf, puis rattacher chaque objet à l’état. Ce module décrit cette démarche, puis la surveillance de la dérive qui la suit.
Sur le plan de la fiabilité, l’enjeu est concret : une configuration qui ne vit que dans l’interface ne se relit pas, ne se revoit pas et ne se restaure pas après une erreur. Le code versionné réduit le temps de remise en état.
Import Terraform Dynatrace SaaS : l’état et ce qu’il contient
Terraform tient un état : la correspondance entre les blocs resource du code et les objets réels de l’environnement. Sans cette correspondance, terraform plan proposerait de créer des doublons de ce qui existe déjà. L’import consiste donc à écrire, dans l’état, le lien entre un bloc et un objet existant.
Pour un travail en équipe, la documentation HashiCorp recommande l’état distant : avec un état local, chaque personne doit s’assurer de disposer de la dernière version avant d’exécuter Terraform, alors que l’état distant peut s’accompagner d’un verrouillage qui empêche deux exécutions simultanées sur le même état. Le choix du backend relève de votre organisation ; ce module ne l’impose pas.
Exporter l’existant avec le provider
Le provider dynatrace-oss/dynatrace peut aussi s’exécuter comme programme autonome pour exporter une configuration. La documentation Dynatrace décrit le déroulement.
- Installer le CLI Terraform et le provider, et créer un jeton de plateforme ou un client OAuth dont les permissions couvrent les objets à lire.
- Définir les variables d’environnement qui désignent l’environnement :
DYNATRACE_ENV_URLet, selon l’authentification,DYNATRACE_PLATFORM_TOKENouDT_CLIENT_ID,DT_CLIENT_SECRETetDT_ACCOUNT_ID. - Facultatif :
DYNATRACE_TARGET_FOLDERfixe le dossier de sortie. Sans elle, le dossier.configurationest utilisé. - Lancer directement l’exécutable du provider, et non
terraform. Il se trouve en général sous.terraform/providers/registry.terraform.io/dynatrace-oss/dynatrace/. La documentation précise que l’avertissement affiché à l’appel direct peut être ignoré.

La forme générale de la commande est :
./terraform-provider-dynatrace -export [-ref] [-migrate] [-import-state] [-id] [-flat] [-exclude] [-admin-access] [<resourcename>[=<id>]]
Les options qui comptent
| Option | Effet (documentation officielle) |
|---|---|
-ref |
Inclut les ressources avec leurs sources de données et leurs dépendances |
-migrate |
Inclut les dépendances, sans les sources de données |
-import-state |
Initialise les modules Terraform et importe les ressources dans l’état |
-id |
Ajoute l’identifiant en commentaire dans les fichiers de ressources |
-flat |
Stocke toutes les ressources directement dans le dossier cible, sans structure de modules |
-exclude |
Exclut les ressources indiquées |
-admin-access |
Exporte les ressources OpenPipeline de tous les propriétaires ; exige la permission settings:objects:admin |
L’option -list-exclusions liste les ressources non exportées par défaut, sans lancer d’export. Les dashboards dynatrace_json_dashboard en font partie : il faut les nommer explicitement pour les exporter. Lancez-la en premier, afin de savoir ce qui manquera.
Importer dans l’état et lire le résultat
Deux chemins existent. Le premier exporte puis importe en une commande avec -import-state. Le second exporte seulement, puis laisse chaque équipe relire le code avant tout import. Pour un premier essai, le second est plus prudent : vous lisez les fichiers générés avant de lier quoi que ce soit.
La documentation donne ces exemples, avec des ressources d’objectifs de niveau de service :
./terraform-provider-dynatrace -export -import-state
./terraform-provider-dynatrace -export -import-state dynatrace_platform_slo
./terraform-provider-dynatrace -export -ref dynatrace_platform_slo dynatrace_automation_workflow
La même page cite d’autres types : dynatrace_document, dynatrace_automation_workflow, et l’option -admin-access pour OpenPipeline. L’export de ces ressources dépend des permissions du jeton ou du client OAuth. La page Terraform du provider liste les portées OAuth correspondantes, comme openpipeline:configurations:read ou document:documents:read.
Les fichiers à examiner à la main
Certains fichiers ne sont pas utilisables tels quels. L’export les déplace dans deux dossiers cachés, avec la raison en commentaire au début de chaque fichier :
.flawed: fichiers obsolètes ou à modifier ;.required_attention: fichiers auxquels il manque l’essentiel pour être appliqués, par exemple à cause de données sensibles. La documentation cite les chaînes confidentielles dedynatrace_credentials, que l’API ne fournit pas.
Traitez ces dossiers comme une liste de tâches : tant qu’ils contiennent des fichiers, l’import est incomplet.
Détecter la dérive
La dérive est l’écart entre le code, l’état et l’environnement réel, par exemple lorsqu’une personne modifie un objet dans l’interface. Deux commandes Terraform standard aident.
terraform plan -refresh-onlycrée un plan dont le but est seulement de mettre à jour l’état et les sorties du module racine, pour qu’ils reflètent des changements faits hors de Terraform.terraform plan -detailed-exitcoderenvoie 0 sans changement, 1 en cas d’erreur et 2 si le plan contient des changements.

Le code de sortie 2 se prête à une vérification planifiée : un plan non vide signale que le code et l’environnement divergent. La mise en place dans un pipeline est l’objet du module suivant.
Réutiliser la configuration entre environnements
L’option -flat évite la structure de modules ; sans elle, l’export organise les ressources en modules. Pour copier une configuration d’un environnement à un autre, la documentation de migration distingue la méthode en bloc (-migrate, vers un environnement cible sans configuration existante) de la méthode itérative (-migrate -datasources, par groupe de ressources). Les variables DYNATRACE_DUPLICATE_REJECT=ALL et DYNATRACE_DUPLICATE_HIJACK=ALL contrôlent le comportement face aux doublons : refuser tout écrasement, ou l’autoriser.
Pour un exemple de ressources écrites à la main, voyez les SLO avec Terraform.
Exercice pratique
Réalisez-le sur un environnement SaaS de test. Les commandes ci-dessous n’ont pas été exécutées pour la rédaction de ce module : leur sortie dépend de votre environnement.
Étape 1 — Préparer
Définissez DYNATRACE_ENV_URL et DYNATRACE_PLATFORM_TOKEN (ou le trio OAuth), puis DYNATRACE_TARGET_FOLDER vers un dossier vide. Résultat attendu : aucune valeur secrète dans l’historique partagé ni dans Git.
Étape 2 — Lister les exclusions
Lancez ./terraform-provider-dynatrace -export -list-exclusions. Résultat attendu : la liste des ressources absentes d’un export par défaut ; repérez-en une qui vous concerne.
Étape 3 — Exporter un type de ressource
Exportez un seul type, par exemple dynatrace_platform_slo, avec -id. Résultat attendu : des fichiers .tf dans le dossier cible, avec l’identifiant en commentaire, et éventuellement des fichiers dans .flawed ou .required_attention.
Étape 4 — Importer puis contrôler
Relancez avec -import-state, puis exécutez terraform plan dans le dossier d’export. Résultat attendu : idéalement aucun changement. S’il en reste, comparez le code généré et l’objet réel avant d’appliquer quoi que ce soit.
Étape 5 — Provoquer une dérive
Modifiez un objet dans l’interface, puis lancez terraform plan -detailed-exitcode. Résultat attendu : un plan non vide et le code de sortie 2.
Quiz
- Quel exécutable lance l’export ? a)
terraformb)terraform-provider-dynatracec)terraform-docsd)oneagentctl - Que fait
-import-state? a) Il supprime l’état b) Il importe les ressources exportées dans l’état Terraform c) Il chiffre les secrets d) Il publie le code sur Git - Où l’export range-t-il les fichiers qui manquent d’informations essentielles ? a)
.flawedb).required_attentionc).stated).flat - Quel code de sortie renvoie
terraform plan -detailed-exitcodequand le plan contient des changements ? a) 0 b) 1 c) 2 d) 3
Corrigé
- b) L’export est une fonction de l’exécutable du provider, appelé directement.
- b) L’option initialise les modules et importe les ressources dans l’état.
- b)
.required_attentionregroupe les fichiers auxquels il manque l’essentiel pour être appliqués ;.flawedcontient les fichiers obsolètes ou à modifier. - c) 0 signifie aucun changement, 1 une erreur, 2 un plan avec changements.
Pour aller plus loin
- Terraform et Dynatrace : alerting et dashboards
- Les schémas de l’API Dynatrace SaaS, pour comprendre les objets exportés
- Documentation officielle : commandes du CLI Terraform et export
- Dépôt du provider Terraform Dynatrace
← Module 1 : provider Terraform · Sommaire du parcours · Module 3 : GitOps →
Questions fréquentes
L’export récupère-t-il toute la configuration ?
Non. Certaines ressources, dont les dashboards dynatrace_json_dashboard, sont exclues par défaut et se demandent explicitement. Les secrets, comme les chaînes confidentielles des identifiants, ne sont pas disponibles par l’API.
Faut-il appeler terraform ou le provider pour exporter ?
Le provider. L’export est une fonction de l’exécutable du provider, que l’on appelle directement ; l’avertissement qui s’affiche alors peut être ignoré, selon la documentation.
Comment savoir si quelqu’un a modifié un objet à la main ?
Exécutez terraform plan, avec -refresh-only pour mettre l’état à jour ou -detailed-exitcode pour obtenir le code 2 en cas de changements.
Le code décrit maintenant ce qui existait déjà, et la dérive se mesure par une commande. Le module 3 place ces vérifications dans un pipeline de revue et de promotion.
span.observer est un blog indépendant de la communauté, non affilié à Dynatrace LLC. Ce parcours ne remplace pas les formations et certifications officielles de Dynatrace University. Vérifiez les fonctionnalités dans la documentation officielle de votre version.