Crear un entorno para una nueva filial, añadir un grupo de usuarios, generar un token para la cadena de despliegue, comprobar el estado de los nodos antes de un mantenimiento: por separado, estas tareas se hacen en unos pocos clics en la Cluster Management Console. Repetidas cada semana, en varios clústeres y por varios administradores, se convierten en una fuente de errores y de desviaciones de configuración, a menos que se las confíes a la API Cluster.
La API Cluster de Dynatrace Managed está pensada para esto. Distinta de la API de entorno (https://{tu-dominio}/e/{id-entorno}/api/…), se dirige al nivel de plataforma: https://{tu-dominio}/api/cluster/v2/… para la v2, y principalmente https://{tu-dominio}/api/v1.0/onpremise/… para la v1. No tiene equivalente para un cliente SaaS, porque quien la necesita es el operador del clúster, es decir, tú.
Este artículo repasa lo que permite, cómo protegerla, y propone scripts concretos para empezar una automatización seria.
¿API Cluster o API de entorno?
| Criterio | API Cluster | API de entorno |
|---|---|---|
| URL base | https://{tu-dominio}/api/cluster/v2 y …/api/v1.0/onpremise (v1) |
https://{tu-dominio}/e/{id}/api/v1|v2 |
| Token | Token de clúster (CMC, Settings > API tokens) | Token de entorno |
| Alcance | Nodos, entornos, usuarios, grupos, licencias, parámetros del clúster | Entidades, métricas, problemas, parámetros de monitorización, despliegue de OneAgent |
| Usuarios típicos | Equipo de plataforma | Equipos de operaciones, CI/CD, herramientas de terceros |
Una automatización completa suele usar ambas: la API Cluster crea el entorno y un primer token de entorno, y la API de entorno toma el relevo para la configuración de la monitorización.
Lo que se automatiza habitualmente
- Ciclo de vida de los entornos: creación, cambio de nombre, activación/desactivación, cuotas (unidades de host, sesiones, almacenamiento).
- Tokens: generación de tokens de entorno para el arranque de herramientas.
- Usuarios y grupos: creación de grupos, asignación de permisos, exportaciones de auditoría (consulta el modelo de acceso de Managed).
- Estado del clúster: lista de nodos, estado, versión; útil antes y después de un mantenimiento.
- Parámetros: SMTP, proxy, copia de seguridad, según lo que exponga tu versión.
La lista exacta de los puntos de acceso depende de la versión de Managed. La referencia que manda es el explorador de la API Cluster accesible desde la CMC, que documenta cada ruta y permite probarla.
Tutorial paso a paso
Paso 1 — Crear un Cluster API token dedicado
En la CMC, abre Settings > API tokens, sección Cluster tokens, y crea un token por uso: audit, provisioning-environnements, etc. Marca solo los permisos necesarios entre Service Provider API (ServiceProviderAPI, necesario para entornos, usuarios, grupos y nodos), Cluster token management, Read settings y Write settings. Guarda el valor en tu gestor de secretos; no se volverá a mostrar.
export DT_CLUSTER="https://{votre-domaine}"
export DT_CTOKEN="{token}" # à charger depuis un coffre, jamais en dur dans un dépôt
Paso 2 — Primera llamada: listar los entornos
curl -s -H "Authorization: Api-Token $DT_CTOKEN" \
-H "Accept: application/json" \
"$DT_CLUSTER/api/cluster/v2/environments" | python3 -m json.tool
Obtienes la lista de entornos con su identificador, nombre, estado y cuotas. Si recibes un 401, la autenticación del token ha fallado: comprueba su validez y sus permisos.
Paso 3 — Crear un entorno de forma idempotente
Un buen script de automatización puede volver a ejecutarse sin efectos secundarios. Por eso se comprueba la existencia antes de crear:
#!/usr/bin/env bash
set -euo pipefail
NOM="${1:?usage: $0 nom-environnement}"
existe=$(curl -s -H "Authorization: Api-Token $DT_CTOKEN" \
"$DT_CLUSTER/api/cluster/v2/environments" \
| python3 -c "import sys,json; d=json.load(sys.stdin); print(any(e.get('name')=='$NOM' for e in d.get('environments',[])))")
if [ "$existe" = "True" ]; then
echo "Environnement $NOM déjà présent, rien à faire."
exit 0
fi
curl -s -X POST -H "Authorization: Api-Token $DT_CTOKEN" \
-H "Content-Type: application/json" \
-d "{\"name\": \"$NOM\", \"state\": \"ENABLED\", \"tags\": [\"provisionne-par-api\"]}" \
"$DT_CLUSTER/api/cluster/v2/environments"
La lista se devuelve en el array environments, paginada (nextPageKey): en un clúster grande, sigue la paginación o aumenta pageSize. La respuesta de creación contiene el identificador del nuevo entorno, que debes conservar para lo siguiente.
Paso 4 — Arrancar el entorno con un token
Al añadir ?createToken=true al POST de creación, la respuesta contiene un tokenManagementToken (scopes apiTokens.read, apiTokens.write y TenantTokenManagement). Permite crear, mediante POST /e/{id}/api/v2/apiTokens, un token de entorno con scopes limitados. Este último sirve para una segunda fase de scripts que aplica la configuración base mediante la API de entorno: etiquetas automáticas, management zones, perfiles de alerta.
export DT_ENV="$DT_CLUSTER/e/{id-environnement}"
curl -s -H "Authorization: Api-Token {token-environnement}" \
"$DT_ENV/api/v2/settings/schemas" | python3 -m json.tool | head -40
Paso 5 — Comprobar el estado de los nodos antes del mantenimiento
Consulta la ruta v1 de información sobre los nodos conocidos del clúster (permiso Service Provider API), que devuelve entre otros su operationState y su versión, y no continúes si un nodo no está en el estado esperado:
curl -s -H "Authorization: Api-Token $DT_CTOKEN" \
"$DT_CLUSTER/api/v1.0/onpremise/cluster" | python3 -m json.tool
Combinada con un systemctl o un df -h /var/opt/dynatrace-managed ejecutado en cada nodo mediante tu herramienta de gestión de configuración, esta comprobación forma una «verificación previa» de mantenimiento fiable.
Paso 6 — Integrar con las herramientas existentes
Las mismas llamadas se integran fácilmente en Ansible (módulo uri), en un pipeline de CI o en Terraform mediante un provider compatible con tu versión. El principio es el mismo: un repositorio Git describe el estado deseado (entornos, grupos, cuotas), y un job lo compara con el estado real y aplica la diferencia.
Buenas prácticas
- Un token por uso, scopes mínimos, fecha de caducidad, rotación planificada.
- Nunca un token en claro en un script, un repositorio o un historial de shell; usa un gestor de secretos y variables de entorno.
- Idempotencia: comprobar antes de crear, actualizar en lugar de recrear.
- Modo «dry-run»: haz que se muestre el plan de acción antes de aplicarlo.
- Gestión de errores: controla el código HTTP (
curl -w "%{http_code}") y respeta los límites de tasa (respuesta 429). - Pruebas de no regresión tras cada actualización de Managed: las API evolucionan, y algunas rutas v1 pueden quedar obsoletas en favor de la v2.
- Trazabilidad: cada acción automatizada debe ser visible en el registro de auditoría y estar vinculada a un commit.
Preguntas frecuentes
¿Qué diferencia hay entre la API Cluster y la API de entorno?
La API Cluster (/api/cluster/v2 y /api/v1.0/onpremise, token de clúster creado en la CMC) cubre la plataforma: nodos, entornos, usuarios, grupos, licencias. La API de entorno (/e/{id}/api/…, token de entorno) cubre la monitorización: entidades, métricas, problemas, parámetros. Una automatización completa suele encadenar ambas.
¿Qué significan los errores 401, 403 y 429?
Un 401 indica un fallo de autenticación del token (inválido, caducado o sin el permiso requerido), un 403 un acceso denegado y un 429 que se han superado los límites de tasa: reduce el ritmo de las llamadas y vuelve a intentarlo más tarde.
¿Dónde encontrar la lista exacta de las rutas disponibles?
En el explorador de la API Cluster accesible desde la CMC: documenta cada ruta de tu versión y permite probarla. Revisa de nuevo tus scripts después de cada actualización, ya que algunas rutas v1 pueden quedar obsoletas en favor de la v2.
Conclusión
La API Cluster es la herramienta que lleva la administración de Dynatrace Managed del clic artesanal a la operación industrial. Empezando por scripts sencillos e idempotentes (inventario, creación de entornos, exportación de auditoría) y después integrándolos con tus herramientas de configuración, ganas velocidad, coherencia entre clústeres y trazabilidad. Todo ello sin salir de los estándares: HTTP, JSON, curl y un gestor de secretos.
span.observer es un blog independiente de la comunidad, no afiliado a Dynatrace LLC. Dynatrace es una marca de Dynatrace LLC. Comprueba siempre los valores (puertos, versiones, tamaños) en la documentación oficial correspondiente a tu versión de Managed.