Automatizas un clúster Managed y cada script empieza con la misma pregunta: ¿a qué URL llamar, con qué token, y existe de verdad ese endpoint en mi versión? La API de Dynatrace Managed no es una sola API, sino dos familias que conviven: la Cluster API, que gobierna el clúster desde la Cluster Management Console (CMC), y la Environment API, que trabaja dentro de un entorno.
Confundirlas sale caro en toil: un token de clúster enviado a un endpoint de entorno, una URL de SaaS copiada de un tutorial, un esquema de Settings que todavía no existe en tu build. El resultado: errores 401, errores 404 y pipelines de automatización que fallan por la noche.
Objetivo de esta guía de referencia: saber en pocos minutos a qué API llamar, con qué token y qué permiso, y cómo listar los esquemas de Settings realmente disponibles en tu clúster. El contenido vale únicamente para Dynatrace Managed; se señalan las diferencias con SaaS.
Las dos familias de la API de Dynatrace Managed
La documentación de Managed distingue claramente dos ámbitos. La Cluster API actúa sobre todo el clúster, aunque aloje varios entornos. La Environment API actúa sobre un entorno concreto, identificado por su ID en la URL.
| Criterio | Cluster API (v1 y v2) | Environment API (v1, v2, config v1) |
|---|---|---|
| Ámbito | Todo el clúster: nodos, entornos, usuarios, licencia, tokens de clúster | Un entorno: entidades, métricas, problemas, Settings, tokens de entorno |
| URL base | https://{cluster}/api/cluster/v2/… y https://{cluster}/api/v1.0/onpremise/… |
https://{cluster}/e/{environment-id}/api/v2/… |
| Dónde crear el token | CMC, Settings > API tokens, sección Cluster tokens | En el entorno, página Access Tokens |
| Permisos típicos | ServiceProviderAPI, ClusterTokenManagement |
settings.read, apiTokens.write, etc. |
| Documentación interactiva | Menú de usuario de la CMC, Cluster API v1 o Cluster API v2 | Explorador de API del entorno |
Para la automatización completa de la administración (creación de entornos en serie, gestión de usuarios), consulta también el tutorial automatizar la administración con la API Cluster. Aquí nos centramos en la cartografía y en las trampas.
Requisitos previos
- Un clúster de Dynatrace Managed y acceso de administrador a la CMC.
- Un token de clúster con el permiso
ServiceProviderAPI(lectura y gestión de entornos, nodos, usuarios, licencia). - Un token de entorno con el scope
settings.readpara listar los esquemas. curlyjqen el equipo que llama a la API.
Ambos tokens se envían en la cabecera Authorization: Api-Token …. Si hay un rechazo, la guía resolver problemas con un token de API de Dynatrace detalla el diagnóstico de los errores 401, 403 y 404.
Paso 1: crear los tokens adecuados
Token de clúster
En la CMC, abre Settings > API tokens; en la sección Cluster tokens, selecciona Generate token. Los permisos documentados para la configuración del clúster son:
| Nombre mostrado | Valor de la API | Uso |
|---|---|---|
| Cluster token management | ClusterTokenManagement |
Gestionar los tokens de clúster mediante la API Tokens |
| Service Provider API | ServiceProviderAPI |
Operaciones de gestión del clúster (entornos, usuarios, nodos, licencia) |
| Read settings | settings.read |
Leer los ajustes a nivel de clúster (API v2) |
| Write settings | settings.write |
Escribir los ajustes a nivel de clúster (API v2) |
Dynatrace recomienda un token por uso, con un único scope si es posible: en caso de fuga, el radio de impacto queda limitado.
Token de gestión de los tokens de entorno
La misma página ofrece una sección Environment token management tokens. Este token sirve para crear, mediante la API, tokens en un entorno concreto. Solo es válido durante 24 horas, por su impacto potencial sobre todos los entornos.
Token de entorno
En el entorno, página Access Tokens, selecciona Generate new token y marca settings.read. Cópialo de inmediato: no se volverá a mostrar.
Paso 2: la tabla de referencia de los endpoints de la Cluster API
Estos son los endpoints más usados a diario, todos verificados en la documentación de Managed. Todos exigen el permiso ServiceProviderAPI, salvo los tokens (ClusterTokenManagement).
| Familia | Método y ruta | Versión |
|---|---|---|
| Entornos | GET / POST /api/cluster/v2/environments |
v2 |
| Entorno concreto | GET / PUT / DELETE /api/cluster/v2/environments/{id} |
v2 |
| Nodos conocidos | GET /api/v1.0/onpremise/cluster |
v1 |
| Configuración de los nodos | GET /api/v1.0/onpremise/cluster/configuration |
v1 |
| Usuarios | GET /api/v1.0/onpremise/users |
v1 |
| Grupos de usuarios | GET /api/v1.0/onpremise/groups |
v1 |
| Licencia (exportación) | GET /api/cluster/v2/license/consumption |
v2 |
| Tokens de clúster | GET / POST /api/cluster/v2/tokens |
v2 |
La Cluster API v1 cubre también el mantenimiento del clúster, el proxy de Internet (incluido por centro de datos en alta disponibilidad), la política de contraseñas, los certificados SSL y el lanzamiento de las actualizaciones. La v2 añade las ubicaciones y los nodos Synthetic privados, las sesiones de usuario, el acceso remoto y el estado de Log Monitoring. La lista exacta depende de tu build: la documentación interactiva de la CMC es la que manda.
Algunos detalles útiles:
GET /api/cluster/v2/environmentsestá paginado:pageSize(100 por defecto, 1000 como máximo),nextPageKey,sort(name,-name,creationDate…) yfilter, por ejemploname(prod).POST /api/cluster/v2/environments?createToken=truedevuelve, además del entorno, un token de gestión de tokens (apiTokens.read,apiTokens.write,TenantTokenManagement) utilizable en el nuevo entorno.- La exportación de la licencia devuelve un archivo ZIP (
application/octet-stream) y solo funciona con el licensing clásico: de lo contrario, respuesta 422.
Para la gestión de cuotas por entorno, consulta gestionar varios entornos y cuotas de licencia en la CMC.
Paso 3: llamar a la Cluster API con 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}'
El segundo comando devuelve, para cada nodo, los campos id, buildVersion y operationState. Es la forma más sencilla de conocer la versión de tu clúster antes de usar un endpoint reciente. Los nombres de campo de la primera respuesta (environments, state) deben comprobarse en tu versión desde el explorador de la CMC.
Paso 4: listar los esquemas de Settings de tu versión
Los esquemas de Settings 2.0 evolucionan con cada versión. Un esquema documentado para SaaS puede no existir todavía en tu clúster. No lo adivines: pide la lista al entorno.
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 respuesta es un objeto SchemaList: un array items y un contador totalCount. El parámetro fields acepta schemaId, displayName, maturity, latestSchemaVersion, multiObject, ordered y ownerBasedAccessControl. El campo maturity vale PREVIEW, EARLY_ADOPTER o GENERAL_AVAILABILITY: para la automatización de producción, prioriza los esquemas GA.
Ejemplo para comprobar que un esquema existe antes de usarlo en Terraform o 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"
A continuación, GET /api/v2/settings/objects?schemaIds=… (scope settings.read) lista los objetos existentes para ese esquema. Si la llamada pasa por un ActiveGate, la URL pasa a ser https://{activegate}:9999/e/{environment-id}/api/v2/….
Lo que no existe en Managed
Muchos ejemplos publicados apuntan a la plataforma SaaS. Antes de copiar una llamada, comprueba que no dependa de alguno de estos componentes, ausentes de Managed:
- las API de la plataforma (URL en
*.apps.dynatrace.com/platform/…), los tokens de plataforma y la autenticación OAuth asociada; - Grail y las consultas DQL mediante la API de almacenamiento;
- AppEngine, las Dynatrace Apps, los Workflows de la plataforma y los Notebooks o Dashboards de nueva generación;
- la Account Management API (
api.dynatrace.com/iam/v1/…): en Managed, usuarios y grupos pasan por la Cluster API v1.
La página de autenticación de la documentación de Managed remite ella misma a la lista de funciones no disponibles en Managed para los tokens de plataforma. En Managed, quédate con la Environment API v1 y v2, la API de configuración v1 y la Cluster API.
Cómo comprobar que funciona
GET /api/v1.0/onpremise/clusterdevuelve un código 200 y la lista de nodos: el token de clúster y la URL son correctos.GET /api/cluster/v2/environmentsdevuelve tus entornos: el permisoServiceProviderAPIestá presente.GET /e/{id}/api/v2/settings/schemasdevuelve untotalCountsuperior a cero: el token de entorno llevasettings.read.- Un token de clúster enviado a
/e/{id}/api/v2/…debe fallar: es normal, las dos familias de tokens están separadas.
Buenas prácticas
- Un token, un uso: un token
ServiceProviderAPIpara el inventario, otro para la gestión de tokens, cada uno con fecha de caducidad. - Versiona la lista de esquemas: expórtala después de cada actualización del clúster y compárala con la anterior. Los esquemas nuevos aparecen sin ruido.
- Respeta los límites de tasa: espacia los bucles sobre todos los entornos, sobre todo en multi-tenant.
- Centraliza los secretos: nunca un token en un repositorio ni en los logs de un pipeline de CI.
- Permisos de acceso: alinea los grupos creados por la API con el modelo descrito en usuarios, grupos y permisos en Managed.
Preguntas frecuentes
¿Qué diferencia hay entre la Cluster API v1 y la v2?
Son dos conjuntos de endpoints complementarios, ambos activos. La v1 (/api/v1.0/onpremise/…) cubre los nodos, el mantenimiento, el proxy, los usuarios, los grupos y los certificados. La v2 (/api/cluster/v2/…) cubre los entornos, los tokens, la licencia y Synthetic. Se usan ambas según el objeto buscado.
¿Puede un token de entorno llamar a la Cluster API?
No. La Cluster API exige un token de clúster creado en la CMC. A la inversa, un token de clúster no sirve para consultar las entidades o las métricas de un entorno.
¿Cómo saber si un esquema de Settings visto en la documentación de SaaS existe en mi clúster?
Llama a GET /e/{id}/api/v2/settings/schemas y busca el schemaId. Si no está, quizá llegue con una versión posterior del clúster; consulta las notas de versión de Managed.
Conclusión
La API de Dynatrace Managed se resume en tres reflejos: la Cluster API para el clúster, con un token de la CMC; la Environment API bajo /e/{id}/api/v2 para todo lo demás; y la lista de esquemas de Settings consultada en tu propia versión antes de cualquier automatización. Con la tabla de referencia anterior y las llamadas con curl, tus scripts dejan de adivinar y las actualizaciones de tu clúster se vuelven previsibles.
Referencia oficial: Cluster API (documentación de Managed) y Settings API, lista de esquemas.
span.observer es un blog independiente de la comunidad, no afiliado a Dynatrace LLC. Dynatrace es una marca de Dynatrace LLC. Los endpoints, permisos y nombres de pantalla evolucionan según las versiones: comprueba siempre los valores (puertos, versiones, tamaños) en la documentación oficial correspondiente a tu versión del clúster.