API Dynatrace Managed : Cluster API v1 et v2, Environment API et schémas Settings disponibles

API Dynatrace Managed : Cluster API v1 et v2, Environment API, URL de base, tokens, permissions et liste des schémas Settings de votre version, en curl.
API Dynatrace Managed : Cluster API v1 et v2, Environment API et schémas Settings disponibles

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.read pour lister les schémas.
  • curl et jq sur 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/environments est paginé : pageSize (100 par défaut, 1000 au maximum), nextPageKey, sort (name, -name, creationDate…) et filter, par exemple name(prod).
  • POST /api/cluster/v2/environments?createToken=true renvoie, 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

  1. GET /api/v1.0/onpremise/cluster renvoie un code 200 et la liste des nœuds : le token de cluster et l’URL sont bons.
  2. GET /api/cluster/v2/environments renvoie vos environnements : la permission ServiceProviderAPI est présente.
  3. GET /e/{id}/api/v2/settings/schemas renvoie un totalCount supérieur à zéro : le token d’environnement porte settings.read.
  4. 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 ServiceProviderAPI pour 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.

Total
0
Shares
Laisser un commentaire

Votre adresse e-mail ne sera pas publiée. Les champs obligatoires sont indiqués avec *

Previous Post
API Dynatrace SaaS : la carte complète des API et des schémas Settings 2.0

API Dynatrace SaaS : la carte complète des API et des schémas Settings 2.0

Next Post
Dashboard Dynatrace SaaS : construire des tableaux de bord DQL sur Grail, avec 3 exemples complets

Dashboard Dynatrace SaaS : construire des tableaux de bord DQL sur Grail, avec 3 exemples complets

Related Posts