API de Dynatrace Managed: Cluster API v1 y v2, Environment API y esquemas de Settings disponibles

API de Dynatrace Managed: Cluster API v1 y v2, Environment API, URL base, tokens, permisos y lista de esquemas de Settings de tu versión, con curl.
API Dynatrace Managed : Cluster API v1 et v2, Environment API et schémas Settings disponibles

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.read para listar los esquemas.
  • curl y jq en 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/environments está paginado: pageSize (100 por defecto, 1000 como máximo), nextPageKey, sort (name, -name, creationDate…) y filter, por ejemplo name(prod).
  • POST /api/cluster/v2/environments?createToken=true devuelve, 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

  1. GET /api/v1.0/onpremise/cluster devuelve un código 200 y la lista de nodos: el token de clúster y la URL son correctos.
  2. GET /api/cluster/v2/environments devuelve tus entornos: el permiso ServiceProviderAPI está presente.
  3. GET /e/{id}/api/v2/settings/schemas devuelve un totalCount superior a cero: el token de entorno lleva settings.read.
  4. 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 ServiceProviderAPI para 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.

Total
0
Shares
Leave a Reply

Your email address will not be published. Required fields are marked *

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

API de Dynatrace SaaS: el mapa completo de las API y de los esquemas de Settings 2.0

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

Dashboard Dynatrace SaaS: construir dashboards DQL sobre Grail, con 3 ejemplos completos

Related Posts