Module 2 du parcours Monaco SaaS : l’installation Monaco SaaS, du téléchargement du CLI à un manifeste qui s’authentifie avec un jeton de plateforme ou un client OAuth.
Parcours : Monaco SaaS · Module 2 · Durée : ~40 min · Niveau : Débutant
Objectifs :
- Installer et vérifier le CLI Monaco
- Écrire un manifeste avec les trois clés de premier niveau
- Choisir entre jeton de plateforme et client OAuth
- Fournir les secrets par variables d’environnement, jamais dans le dépôt
Prérequis : le module 1, un environnement Dynatrace SaaS de test et un terminal.
Un outil de configuration as code ne vaut que si son point de départ est reproductible. L’installation Monaco SaaS tient en trois gestes : placer le binaire sur le poste ou dans l’image CI, décrire l’environnement visé dans un manifeste, puis fournir les identifiants par variables d’environnement. Ce module couvre uniquement Dynatrace SaaS. Pour un cluster Managed, le parcours Managed a ses propres modules.
L’enjeu côté SRE est concret : un manifeste versionné et des secrets hors du dépôt réduisent le toil des déploiements manuels et rendent chaque changement relisible, donc plus facile à annuler en cas d’incident.
Installation Monaco SaaS : installer le CLI
La documentation officielle propose trois voies : télécharger le binaire, utiliser l’image de conteneur, puis lancer la commande monaco. Les binaires existent pour Linux (amd64, arm64, 386), macOS et Windows (amd64, 386). Sous Linux amd64, la documentation donne la séquence suivante : téléchargement, contrôle facultatif de la somme de contrôle, renommage, droit d’exécution, copie dans le PATH.

Le contrôle de somme est marqué « optionnel » dans la documentation, mais il coûte une seconde : conservez-le dans vos scripts d’installation. Sous Windows, la documentation utilise Invoke-WebRequest dans PowerShell pour récupérer monaco.exe.
Pour vérifier l’installation, lancez monaco version : la sous-commande « version » affiche la version du CLI. Lancée sans argument, monaco liste les commandes disponibles, dont deploy, download, delete, generate et account.
Les versions comptent : la prise en charge du jeton de plateforme dans le manifeste exige Monaco 2.24.0 ou plus récent, selon la documentation. Notez la version dans votre procédure.
Le manifeste : trois clés de premier niveau
Le manifeste décrit quoi déployer et où. Il comporte trois clés de premier niveau : manifestVersion, projects et environmentGroups. La version de manifeste actuellement prise en charge est 1.0.
projects: la liste des projets. Chaque entrée porte unname(sans barre oblique) et, en option, unpath; sanspath, le nom sert de chemin. Un projet de typegroupingcharge tous les sous-dossiers comme autant de projets simples.environmentGroups: des groupes d’environnements, par exemple « dev » et « prod ». Appliquer une configuration à un groupe l’applique à tous ses environnements.- Chaque environnement a un
nameinterne unique, uneurlet une sectionauth.

Dans l’exemple, url utilise type: environment : la valeur DT_TEST_URL est le nom d’une variable d’environnement qui contient l’URL. La documentation permet aussi de la saisir directement avec type: value. Les noms DT_TEST_URL et DT_TEST_PLATFORM_TOKEN sont des exemples choisis pour ce cours.
URL SaaS : l’adresse de la plateforme
L’URL attendue pour les API de la plateforme a la forme https://<id-environnement>.apps.dynatrace.com. Le code de Monaco rejette une URL « classique » lorsqu’on s’authentifie avec un client OAuth ou un jeton de plateforme, et son message d’erreur le dit. Monaco en déduit lui-même l’adresse classique en remplaçant .apps. par .live., puis vérifie qu’elle répond. Si ce test échoue, il interroge l’API de métadonnées de la plateforme.
Conséquence pratique : ne saisissez jamais l’URL en .live.dynatrace.com dans le manifeste. Utilisez toujours l’URL en .apps..
Authentification : jeton d’accès, jeton de plateforme ou OAuth
La section auth accepte trois méthodes, et la documentation impose une règle : Monaco ne permet pas d’écrire les secrets dans le manifeste. Le champ name contient le nom de la variable d’environnement qui porte le secret, jamais le secret lui-même.
| Méthode | Clés du manifeste | Sert pour |
|---|---|---|
| Jeton d’accès | token → name |
API de configuration et Settings (portées v1 et v2) |
| Jeton de plateforme | platformToken → name |
API de la plateforme (workflows, documents, buckets Grail…), depuis Monaco 2.24.0 |
| Client OAuth | oAuth → clientId et clientSecret → name |
Mêmes API de la plateforme |
Règles de combinaison : on peut associer token à platformToken ou à oAuth pour un même environnement, mais pas platformToken et oAuth ensemble. Les jetons d’accès et les jetons de plateforme ne sont pas interchangeables.
Portées minimales
Pour un jeton de plateforme ou un client OAuth, la documentation recommande au minimum app-engine:apps:run (métadonnées de la plateforme), settings:objects:read, settings:objects:write et settings:schemas:read. D’autres portées s’ajoutent selon les ressources gérées : automation:workflows:read et write, document:documents:*, storage:bucket-definitions:*, slo:slos:read et write, entre autres. Le principe du moindre privilège s’applique : n’accordez que ce que vos projets déploient.
Pour un jeton d’accès, la documentation cite au minimum DataExport, ReadConfig, WriteConfig, settings.read et settings.write.
Quel choix faire ?
Le jeton de plateforme est le plus simple à mettre en place : un seul secret. Le client OAuth passe par Account Management (Identity & access management, puis OAuth clients) ; le secret n’est affiché qu’à la création, et les politiques IAM des groupes du service user peuvent restreindre davantage les droits. Notez enfin que le jeton de plateforme exige une version récente du CLI. Le module sur OAuth et les secrets approfondit la gestion des secrets en CI.
Exercice pratique
Cet exercice se déroule sur un environnement SaaS de test (essai gratuit possible). Aucune commande n’a été exécutée pour la rédaction : la sortie exacte dépend de votre version.
Étape 1 — Installer et vérifier
Suivez la séquence du téléchargement ci-dessus pour votre système, puis lancez monaco version. Résultat attendu : la commande affiche la version du CLI. Relevez-la.
Étape 2 — Créer le jeton ou le client
Créez un jeton de plateforme (ou un client OAuth) avec les quatre portées minimales citées plus haut. Conservez le secret dans un gestionnaire, pas dans un fichier du dépôt.
Étape 3 — Exporter les variables
export DT_TEST_URL="https://<id-environnement>.apps.dynatrace.com"
export DT_TEST_PLATFORM_TOKEN="<jeton de plateforme>"
Étape 4 — Écrire le manifeste
Créez manifest.yaml comme dans la capture, ainsi qu’un dossier general pour le projet. Le dossier peut rester vide à ce stade ; les configurations arrivent au module 4.
Étape 5 — Valider
Lancez monaco deploy manifest.yaml --dry-run. La documentation du drapeau précise qu’il valide la structure du manifeste, des projets et des configurations, mais pas le contenu des JSON. Non vérifié : si ce mode contacte l’environnement pour tester les identifiants. Une erreur d’authentification signale généralement une URL en .live., une variable absente ou une portée manquante.
Quiz
- Quelles sont les trois clés de premier niveau d’un manifeste ? (a)
name,url,auth; (b)manifestVersion,projects,environmentGroups; (c)token,oAuth,platformToken. - Que contient le champ
namesousplatformToken? (a) le jeton ; (b) le nom de la variable d’environnement qui contient le jeton ; (c) le nom du projet. - Quelle combinaison est interdite pour un même environnement ? (a)
tokenetoAuth; (b)tokenetplatformToken; (c)platformTokenetoAuth. - Quelle forme d’URL faut-il saisir pour les API de la plateforme ? (a)
…live.dynatrace.com; (b)…apps.dynatrace.com; (c) l’adresse IP du serveur.
Corrigé
- (b) : le manifeste se compose de la version, des projets et des groupes d’environnements.
- (b) : Monaco charge toujours les secrets depuis l’environnement, jamais depuis le fichier.
- (c) : un jeton d’accès peut accompagner l’un ou l’autre, mais pas les deux méthodes de plateforme à la fois.
- (b) : Monaco déduit lui-même l’adresse classique à partir de l’URL de la plateforme.
Pour aller plus loin
- Dynatrace Monaco : la configuration en code, pas à pas
- Monaco ou Terraform pour la configuration Dynatrace
- Les schémas de l’API Dynatrace SaaS
- Documentation officielle : ressources Monaco
- Dépôt Dynatrace Configuration as Code (Apache 2.0)
← Module 1 : configuration as code SaaS · Sommaire du parcours · Module 3 : export Monaco SaaS →
Questions fréquentes
Faut-il un jeton d’accès en plus du jeton de plateforme ?
Seulement si vos projets utilisent des API de configuration classiques. Les deux se déclarent côte à côte dans auth, chacun avec sa variable.
Peut-on mettre le jeton directement dans le manifeste ?
Non. La documentation précise que Monaco charge toujours les informations d’authentification depuis des variables d’environnement.
Monaco fonctionne-t-il dans un conteneur ?
La documentation officielle propose une image de conteneur ; consultez sa page de téléchargement pour la référence exacte.
Vous disposez maintenant d’un CLI vérifié et d’un manifeste authentifié par variables d’environnement. Le module suivant utilise cette base pour exporter une configuration existante.
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.