Module 3 du parcours Monaco SaaS : l’export Monaco SaaS avec monaco download transforme une configuration existante en fichiers versionnables.
Parcours : Monaco SaaS · Module 3 · Durée : ~40 min · Niveau : Intermédiaire
Objectifs :
- Lancer
monaco downloadavec un manifeste ou avec une URL - Choisir le périmètre exporté avec les options
--only-* - Lire la structure générée : manifeste, dossiers de types,
config.yamlet gabarits JSON - Connaître les limites de l’export avant de redéployer
Prérequis : Monaco installé et un manifeste fonctionnel (module 2), un environnement Dynatrace SaaS de test, un client OAuth ou un jeton de plateforme.
Un environnement SaaS vit rarement à partir d’un dépôt Git : des alertes, des zones et des paramètres y ont été créés à la main au fil des ans. L’export Monaco SaaS est le point de départ le plus rapide pour reprendre la main. Il lit l’environnement et écrit des fichiers que vous pouvez relire, comparer et versionner. Ce module couvre uniquement Dynatrace SaaS ; Managed a son propre parcours.
Export Monaco SaaS : ce que fait monaco download
La commande interroge les API de l’environnement et écrit sur disque un manifeste et un projet. Elle ne modifie rien dans Dynatrace : c’est une lecture. Pour la fiabilité, cela sert trois usages : sauvegarder une configuration avant un changement risqué, initialiser un dépôt de configuration as code, et comparer deux environnements.
Deux modes existent, selon la documentation officielle des commandes Monaco.
| Mode | Options clés | Quand l’utiliser |
|---|---|---|
| Avec manifeste | --manifest (-m), --environment (-e) |
Le manifeste du module 2 décrit déjà l’environnement et son authentification |
| Avec URL | --url et --oauth-client-id + --oauth-client-secret, ou --platform-token |
Un export ponctuel, sans manifeste préalable |
Les deux modes sont exclusifs : --url ne se combine pas avec --manifest. Les options d’identifiants prennent le nom d’une variable d’environnement, pas la valeur du secret. Les deux options OAuth vont toujours ensemble, et un client OAuth ne se combine pas avec un jeton de plateforme.

Droits nécessaires : scopes OAuth du client
L’export ne peut lire que ce que le client ou le jeton a le droit de voir. La page officielle de création d’un client OAuth pour Monaco liste les scopes par usage. Pour une lecture, retenez :
app-engine:apps:run: métadonnées de l’environnement ;settings:objects:readetsettings:schemas:read: objets et schémas Settings 2.0 ;automation:workflows:read,automation:calendars:read,automation:rules:read: Automation ;storage:bucket-definitions:read: buckets Grail ;document:documents:read: documents ;storage:filter-segments:read: segments ;slo:slos:read: SLO.
Le contrôle des scopes de chaque type figure dans la page « Monaco API support and access permission handling ». Les permissions du client peuvent aussi être restreintes par les politiques des groupes de l’utilisateur de service : vérifiez que ses groupes accordent les mêmes scopes. L’option --admin-access, qui exporte les ressources OpenPipeline de tous les propriétaires, exige la permission settings:objects:admin. Les scopes propres à un jeton de plateforme ne figurent pas dans les pages lues pour ce module : consultez le guide officiel de création de ce jeton.
Choisir le périmètre de l’export
Sans option de périmètre, la documentation ne précise pas ce qui est téléchargé : ciblez donc explicitement. Les options publiées sont :
--only-settings: objets Settings 2.0 uniquement ;--settings-schema(-s) en cible un ou plusieurs schémas ;--only-apiset--api(-a) : API de configuration classiques ;--only-automation,--only-buckets,--only-documents,--only-segments,--only-slo-v2: un type précis.
Plusieurs options --only-* se combinent dans une même commande. Commencez petit : un schéma ou un type, puis élargissez. Un export ciblé est plus rapide et plus facile à relire en revue.
Lire la structure générée
Le dossier de sortie (option --output-folder, -o) reçoit un fichier manifest.yaml et un dossier de projet dont le nom vient de --project (-p, valeur par défaut project). Sans -o, le dossier s’appelle download suivi de l’horodatage. Dans le projet, le code source de Monaco crée un sous-dossier par type de configuration, nommé d’après l’API ou le schéma dont les caractères spéciaux (les deux-points, par exemple) sont retirés. Chacun contient un config.yaml et des gabarits JSON.
Le fichier config.yaml déclare des configurations : un id, un type (ici un schéma Settings 2.0 et sa portée), un nom, un gabarit JSON et des paramètres. Cet extrait provient d’un fichier de test du dépôt Monaco ; il illustre le format, pas une sortie d’export réelle.

Remarquez le paramètre managementZoneId du profil : il référence la configuration zone sous la forme [ schéma, id, propriété ]. Lors de l’export, Monaco remplace les identifiants Dynatrace connus par de telles références, ce qui crée des dépendances entre configurations. Le module 4 les exploite au déploiement.
Si un manifeste existe déjà dans le dossier, Monaco ne l’écrase pas sans --force : il crée un manifest_ horodaté. Le dossier de projet suit la même règle, avec un suffixe horodaté. Le manifeste généré ne contient pas les secrets, seulement les noms des variables d’environnement lues.
Limites de l’export
- Types exclus. Les types
aws-credentials,azure-credentials,kubernetes-credentials,credential-vaultetextensionne sont pas téléchargés ; les configurations en lecture seule sont ignorées par défaut. - Filtres désactivables. Avec
MONACO_FEAT_DOWNLOAD_FILTER=false(CLI 2.2.0 ou plus), tout est téléchargé, mais la documentation prévient qu’un tel projet ne se déploie pas automatiquement sans retouche manuelle. - Dépendances circulaires. En fin d’export, Monaco cherche les cycles et avertit s’il en trouve : ils sont à résoudre à la main.
- Un export n’est pas une preuve de fidélité. Relisez et déployez à blanc (module 4) avant d’appliquer ailleurs.
La variable MONACO_CONCURRENT_REQUESTS (5 par défaut) règle le nombre de requêtes simultanées : baissez-la si le réseau limite ou coupe les appels.
Exercice pratique
Les commandes ci-dessous n’ont pas été exécutées pour cet article ; la sortie exacte dépend de votre environnement et de la version de Monaco. Utilisez un environnement de test.
Étape 1 — Préparer les identifiants
Créez un client OAuth avec les scopes de lecture listés plus haut. Placez l’identifiant et le secret dans deux variables d’environnement (par exemple OAUTH_CLIENT_ID et OAUTH_CLIENT_SECRET). Ne les écrivez jamais dans un fichier du dépôt.
Étape 2 — Exporter les objets Settings 2.0
export DT_URL="URL_DE_VOTRE_ENVIRONNEMENT_SAAS"
monaco download --url "$DT_URL" \
--oauth-client-id OAUTH_CLIENT_ID \
--oauth-client-secret OAUTH_CLIENT_SECRET \
-p export-saas -o export --only-settings
Résultat attendu : un dossier export avec un manifest.yaml et un dossier export-saas, ainsi que le message final « Finished download » et un message sur les dépendances circulaires dans les journaux.
Étape 3 — Lire le résultat
Ouvrez le manifeste : vérifiez qu’il cite des noms de variables, pas de secret. Parcourez un sous-dossier : repérez le config.yaml, un gabarit JSON, puis une référence entre deux configurations.
Étape 4 — Versionner
Initialisez un dépôt Git, validez l’export tel quel, puis relancez la commande plus tard : la différence entre les deux validations montre la dérive de l’environnement.
Bonnes pratiques
- Exportez par périmètre (un schéma, un type) plutôt qu’en bloc.
- Gardez l’export brut dans un commit séparé des retouches.
- Utilisez un client OAuth dédié, en lecture seule pour l’export.
- Ne commitez jamais de valeur de secret.
Quiz
- Que reçoivent les options
--oauth-client-idet--oauth-client-secret?- A. La valeur de l’identifiant et du secret
- B. Le nom d’une variable d’environnement
- C. Un chemin de fichier
- Peut-on combiner
--urlet--manifest?- A. Oui, toujours
- B. Oui, si l’environnement est nommé
- C. Non, ils sont exclusifs
- Lequel de ces types n’est pas téléchargé par défaut ?
- A.
credential-vault - B. Un schéma Settings 2.0 modifiable
- C. Un bucket
- A.
- Que contient chaque sous-dossier de type du projet exporté ?
- A. Un
config.yamlet des gabarits JSON - B. Les journaux de l’environnement
- C. Uniquement le manifeste
- A. Un
Corrigé
- B : les options prennent le nom de la variable, le secret reste hors des commandes et du manifeste.
- C : la documentation les déclare mutuellement exclusifs.
- A : les types portant des identifiants sont exclus de l’export.
- A : un
config.yamldéclare les configurations, les gabarits JSON portent leur contenu.
Pour aller plus loin
- Monaco et la configuration as code Dynatrace
- Monaco ou Terraform pour configurer Dynatrace
- Les API Dynatrace SaaS et les schémas Settings
- Gérer des SLO Dynatrace avec Terraform
- Référence officielle des commandes Monaco (SaaS)
- Créer un client OAuth pour Monaco
← Module 2 : Installation de Monaco · Sommaire du parcours · Module 4 : Déploiement avec Monaco →
Questions fréquentes
L’export modifie-t-il l’environnement Dynatrace ?
Non. La commande lit les configurations et écrit des fichiers locaux. Seul le déploiement, au module 4, modifie l’environnement.
Peut-on redéployer tel quel un export ?
Souvent, mais pas toujours. Les types exclus manquent, et des dépendances circulaires ou des objets propres à l’environnement d’origine peuvent bloquer. Relisez, puis déployez à blanc avant tout.
Les secrets sont-ils exportés ?
Non : les types d’identifiants sont exclus, et le manifeste ne stocke que des noms de variables d’environnement. Les secrets restent à fournir au déploiement, sujet du module 5.
Vous savez désormais transformer un environnement SaaS en projet Monaco lisible et versionnable. Le module suivant déploie ces fichiers : projets, gabarits, dépendances et exécution à blanc.
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.