Vous automatisez un cluster Managed et chaque script commence par la même question : quelle URL appeler, avec quel token, et cet endpoint existe-t-il vraiment sur ma version ? L’API Dynatrace Managed n’est pas une seule API, mais deux familles qui vivent côte à côte : la Cluster API, qui pilote le cluster depuis la Cluster Management Console (CMC), et l’Environment API, qui travaille à l’intérieur d’un environnement.
Confondre les deux coûte cher en toil : un token de cluster envoyé à un endpoint d’environnement, une URL SaaS copiée d’un tutoriel, un schéma Settings qui n’existe pas encore sur votre build. Résultat : des 401, des 404 et des pipelines d’automatisation qui échouent la nuit.
Objectif de ce guide de référence : savoir en quelques minutes quelle API appeler, avec quel token et quelle permission, et comment lister les schémas Settings réellement disponibles sur votre cluster. Le contenu vaut pour Dynatrace Managed uniquement ; les différences avec SaaS sont signalées.
Les deux familles de l’API Dynatrace Managed
La documentation Managed distingue clairement deux périmètres. La Cluster API agit sur le cluster entier, même s’il héberge plusieurs environnements. L’Environment API agit sur un environnement précis, identifié par son ID dans l’URL.
| Critère | Cluster API (v1 et v2) | Environment API (v1, v2, config v1) |
|---|---|---|
| Périmètre | Tout le cluster : nœuds, environnements, utilisateurs, licence, tokens de cluster | Un environnement : entités, métriques, problèmes, Settings, tokens d’environnement |
| URL de base | https://{cluster}/api/cluster/v2/… et https://{cluster}/api/v1.0/onpremise/… |
https://{cluster}/e/{environment-id}/api/v2/… |
| Où créer le token | CMC, Settings > API tokens, section Cluster tokens | Dans l’environnement, page Access Tokens |
| Permissions typiques | ServiceProviderAPI, ClusterTokenManagement |
settings.read, apiTokens.write, etc. |
| Documentation interactive | Menu utilisateur de la CMC, Cluster API v1 ou Cluster API v2 | Explorateur d’API de l’environnement |
Pour l’automatisation complète de l’administration (création d’environnements en série, gestion des utilisateurs), voir aussi le tutoriel automatiser l’administration avec l’API Cluster. Ici, on se concentre sur la cartographie et les pièges.
Prérequis
- Un cluster Dynatrace Managed et un accès administrateur à la CMC.
- Un token de cluster avec la permission
ServiceProviderAPI(lecture et gestion des environnements, nœuds, utilisateurs, licence). - Un token d’environnement avec le scope
settings.readpour lister les schémas. curletjqsur le poste qui appelle l’API.
Les deux tokens s’envoient dans l’en-tête Authorization: Api-Token …. En cas de refus, le guide dépanner un token API Dynatrace détaille le diagnostic 401, 403 et 404.
Étape 1 : créer les bons tokens
Token de cluster
Dans la CMC, ouvrez Settings > API tokens, puis dans la section Cluster tokens, sélectionnez Generate token. Les permissions documentées pour la configuration du cluster sont :
| Nom affiché | Valeur API | Usage |
|---|---|---|
| Cluster token management | ClusterTokenManagement |
Gérer les tokens de cluster via l’API Tokens |
| Service Provider API | ServiceProviderAPI |
Opérations de gestion du cluster (environnements, utilisateurs, nœuds, licence) |
| Read settings | settings.read |
Lire les réglages de niveau cluster (API v2) |
| Write settings | settings.write |
Écrire les réglages de niveau cluster (API v2) |
Dynatrace recommande un token par usage, avec un seul scope si possible : en cas de fuite, le rayon d’impact reste limité.
Token de gestion des tokens d’environnement
La même page propose une section Environment token management tokens. Ce token sert à créer, via l’API, des tokens dans un environnement donné. Il n’est valable que 24 heures, à cause de son impact potentiel sur tous les environnements.
Token d’environnement
Dans l’environnement, page Access Tokens, sélectionnez Generate new token et cochez settings.read. Copiez-le immédiatement : il ne sera plus affiché.
Étape 2 : la table de référence des endpoints Cluster API
Voici les endpoints les plus utilisés au quotidien, tous vérifiés dans la documentation Managed. Ils exigent tous la permission ServiceProviderAPI, sauf les tokens (ClusterTokenManagement).
| Famille | Méthode et chemin | Version |
|---|---|---|
| Environnements | GET / POST /api/cluster/v2/environments |
v2 |
| Environnement précis | GET / PUT / DELETE /api/cluster/v2/environments/{id} |
v2 |
| Nœuds connus | GET /api/v1.0/onpremise/cluster |
v1 |
| Configuration des nœuds | GET /api/v1.0/onpremise/cluster/configuration |
v1 |
| Utilisateurs | GET /api/v1.0/onpremise/users |
v1 |
| Groupes d’utilisateurs | GET /api/v1.0/onpremise/groups |
v1 |
| Licence (export) | GET /api/cluster/v2/license/consumption |
v2 |
| Tokens de cluster | GET / POST /api/cluster/v2/tokens |
v2 |
La Cluster API v1 couvre aussi la maintenance du cluster, le proxy Internet (y compris par datacenter en haute disponibilité), la politique de mots de passe, les certificats SSL et le déclenchement des mises à jour. La v2 ajoute les emplacements et nœuds Synthetic privés, les sessions utilisateurs, l’accès distant et le statut Log Monitoring. La liste exacte dépend de votre build : la documentation interactive de la CMC fait foi.
Quelques détails utiles :
GET /api/cluster/v2/environmentsest paginé :pageSize(100 par défaut, 1000 au maximum),nextPageKey,sort(name,-name,creationDate…) etfilter, par exemplename(prod).POST /api/cluster/v2/environments?createToken=truerenvoie, en plus de l’environnement, un token de gestion des tokens (apiTokens.read,apiTokens.write,TenantTokenManagement) utilisable dans le nouvel environnement.- L’export de licence renvoie un fichier ZIP (
application/octet-stream) et ne fonctionne qu’avec le licensing classique : sinon, réponse 422.
Pour la gestion des quotas par environnement, voir gérer plusieurs environnements et quotas de licence dans la CMC.
Étape 3 : appeler la Cluster API en curl
export DT_CLUSTER="https://managed.example.com"
export DT_CLUSTER_TOKEN="dt0c01.XXXX..." # token de cluster, ServiceProviderAPI
# Lister les environnements (nom et ID), triés par nom
curl -s "$DT_CLUSTER/api/cluster/v2/environments?pageSize=100&sort=name" \
-H "Authorization: Api-Token $DT_CLUSTER_TOKEN" \
-H "accept: application/json" | jq '.environments[] | {id, name, state}'
# Lister les nœuds connus et leur version
curl -s "$DT_CLUSTER/api/v1.0/onpremise/cluster" \
-H "Authorization: Api-Token $DT_CLUSTER_TOKEN" \
| jq '.[] | {id, buildVersion, operationState}'
La deuxième commande renvoie, pour chaque nœud, les champs id, buildVersion et operationState. C’est le moyen le plus simple de connaître la version de votre cluster avant d’utiliser un endpoint récent. Les noms de champs de la première réponse (environments, state) sont à contrôler sur votre version dans l’explorateur de la CMC.
Étape 4 : lister les schémas Settings de votre version
Les schémas Settings 2.0 évoluent à chaque version. Un schéma documenté pour SaaS peut ne pas exister encore sur votre cluster. Ne devinez pas : demandez la liste à l’environnement.
export DT_ENV="https://managed.example.com/e/abc12345-6789"
export DT_ENV_TOKEN="dt0c01.YYYY..." # token d'environnement, settings.read
curl -s "$DT_ENV/api/v2/settings/schemas?fields=schemaId,displayName,latestSchemaVersion,maturity" \
-H "Authorization: Api-Token $DT_ENV_TOKEN" \
| jq -r '.items[] | [.schemaId, .latestSchemaVersion, .maturity] | @tsv' | sort
La réponse est un objet SchemaList : un tableau items et un compteur totalCount. Le paramètre fields accepte schemaId, displayName, maturity, latestSchemaVersion, multiObject, ordered et ownerBasedAccessControl. Le champ maturity vaut PREVIEW, EARLY_ADOPTER ou GENERAL_AVAILABILITY : pour l’automatisation de production, privilégiez les schémas GA.
Exemple pour vérifier qu’un schéma existe avant de l’utiliser dans Terraform ou Monaco :
curl -s "$DT_ENV/api/v2/settings/schemas?fields=schemaId" \
-H "Authorization: Api-Token $DT_ENV_TOKEN" \
| jq -e '.items[] | select(.schemaId == "builtin:alerting.profile")' \
&& echo "schéma disponible" || echo "schéma absent sur cette version"
Ensuite, GET /api/v2/settings/objects?schemaIds=… (scope settings.read) liste les objets existants pour ce schéma. Si l’appel passe par un ActiveGate, l’URL devient https://{activegate}:9999/e/{environment-id}/api/v2/….
Ce qui n’existe pas en Managed
Beaucoup d’exemples publiés ciblent la plateforme SaaS. Avant de copier un appel, vérifiez qu’il ne dépend pas de l’une de ces briques, absentes de Managed :
- les API de la plateforme (URL en
*.apps.dynatrace.com/platform/…), les tokens de plateforme et l’authentification OAuth associée ; - Grail et les requêtes DQL via l’API de stockage ;
- AppEngine, les Dynatrace Apps, les Workflows de la plateforme et les Notebooks ou Dashboards nouvelle génération ;
- l’Account Management API (
api.dynatrace.com/iam/v1/…) : en Managed, utilisateurs et groupes passent par la Cluster API v1.
La page d’authentification de la documentation Managed renvoie elle-même vers la liste des fonctions indisponibles en Managed pour les tokens de plateforme. Côté Managed, restez sur l’Environment API v1 et v2, l’API de configuration v1 et la Cluster API.
Comment vérifier que ça fonctionne
GET /api/v1.0/onpremise/clusterrenvoie un code 200 et la liste des nœuds : le token de cluster et l’URL sont bons.GET /api/cluster/v2/environmentsrenvoie vos environnements : la permissionServiceProviderAPIest présente.GET /e/{id}/api/v2/settings/schemasrenvoie untotalCountsupérieur à zéro : le token d’environnement portesettings.read.- Un token de cluster envoyé sur
/e/{id}/api/v2/…doit échouer : c’est normal, les deux familles de tokens sont séparées.
Bonnes pratiques
- Un token, un usage : un token
ServiceProviderAPIpour l’inventaire, un autre pour la gestion des tokens, chacun avec une date d’expiration. - Versionnez la liste des schémas : exportez-la après chaque mise à jour du cluster et comparez-la avec la précédente. Les nouveaux schémas apparaissent sans bruit.
- Respectez les limites de débit : temporisez les boucles sur tous les environnements, surtout en multi-tenant.
- Centralisez les secrets : jamais de token dans un dépôt ni dans les logs d’un pipeline CI.
- Droits d’accès : alignez les groupes créés par l’API sur le modèle décrit dans utilisateurs, groupes et permissions en Managed.
Questions fréquentes
Quelle est la différence entre Cluster API v1 et v2 ?
Ce sont deux ensembles d’endpoints complémentaires, tous deux actifs. La v1 (/api/v1.0/onpremise/…) couvre les nœuds, la maintenance, le proxy, les utilisateurs, les groupes et les certificats. La v2 (/api/cluster/v2/…) couvre les environnements, les tokens, la licence et Synthetic. On utilise les deux selon l’objet visé.
Un token d’environnement peut-il appeler la Cluster API ?
Non. La Cluster API exige un token de cluster créé dans la CMC. Inversement, un token de cluster ne sert pas à interroger les entités ou les métriques d’un environnement.
Comment savoir si un schéma Settings vu dans la documentation SaaS existe chez moi ?
Appelez GET /e/{id}/api/v2/settings/schemas et cherchez le schemaId. S’il est absent, il arrivera peut-être avec une version ultérieure du cluster ; vérifiez les notes de version Managed.
Conclusion
L’API Dynatrace Managed tient en trois réflexes : la Cluster API pour le cluster, avec un token de la CMC ; l’Environment API sous /e/{id}/api/v2 pour le reste ; et la liste des schémas Settings interrogée sur votre propre version avant toute automatisation. Avec la table de référence ci-dessus et les appels curl, vos scripts cessent de deviner et vos mises à jour de cluster deviennent prévisibles.
Référence officielle : Cluster API (documentation Managed) et Settings API, liste des schémas.
span.observer est un blog indépendant de la communauté, non affilié à Dynatrace LLC. Dynatrace est une marque de son propriétaire. Les endpoints, permissions et noms d’écrans évoluent selon les versions : vérifiez-les dans la documentation officielle de votre cluster.