Módulo 2 de la ruta Monaco SaaS: la instalación de Monaco SaaS, desde la descarga del CLI hasta un manifiesto que se autentica con un token de plataforma o un cliente OAuth.
Ruta: Monaco SaaS · Módulo 2 · Duración: ~40 min · Nivel: Principiante
Objetivos:
- Instalar y comprobar el CLI de Monaco
- Escribir un manifiesto con las tres claves de primer nivel
- Elegir entre token de plataforma y cliente OAuth
- Aportar los secretos mediante variables de entorno, nunca en el repositorio
Requisitos previos: el módulo 1, un entorno Dynatrace SaaS de pruebas y un terminal.
Una herramienta de configuración como código solo vale si su punto de partida es reproducible. La instalación de Monaco SaaS se resume en tres gestos: colocar el binario en el equipo o en la imagen de CI, describir el entorno de destino en un manifiesto y aportar las credenciales mediante variables de entorno. Este módulo cubre únicamente Dynatrace SaaS. Para un clúster Managed, la ruta Managed tiene sus propios módulos.
Para un SRE, lo que está en juego es concreto: un manifiesto versionado y secretos fuera del repositorio reducen el toil de los despliegues manuales y hacen que cada cambio sea revisable y, por tanto, más fácil de revertir en caso de incidente.
Instalación de Monaco SaaS: instalar el CLI
La documentación oficial ofrece tres vías: descargar el binario, usar la imagen de contenedor y ejecutar el comando monaco. Hay binarios para Linux (amd64, arm64, 386), macOS y Windows (amd64, 386). En Linux amd64, la documentación da la siguiente secuencia: descarga, comprobación opcional de la suma de verificación, renombrado, permiso de ejecución y copia en el PATH.

La comprobación de la suma figura como «opcional» en la documentación, pero cuesta un segundo: consérvala en tus scripts de instalación. En Windows, la documentación usa Invoke-WebRequest en PowerShell para obtener monaco.exe.
Para comprobar la instalación, ejecuta monaco version: el subcomando «version» muestra la versión del CLI. Sin argumentos, monaco lista los comandos disponibles, entre ellos deploy, download, delete, generate y account.
Las versiones importan: según la documentación, la compatibilidad con el token de plataforma en el manifiesto exige Monaco 2.24.0 o posterior. Anota la versión en tu procedimiento.
El manifiesto: tres claves de primer nivel
El manifiesto describe qué desplegar y dónde. Tiene tres claves de primer nivel: manifestVersion, projects y environmentGroups. La versión de manifiesto compatible actualmente es 1.0.
projects: la lista de proyectos. Cada entrada lleva unname(sin barra oblicua) y, de forma opcional, unpath; sinpath, el nombre hace de ruta. Un proyecto de tipogroupingcarga todas las subcarpetas como otros tantos proyectos simples.environmentGroups: grupos de entornos, por ejemplo «dev» y «prod». Aplicar una configuración a un grupo la aplica a todos sus entornos.- Cada entorno tiene un
nameinterno único, unaurly una secciónauth.

En el ejemplo, url usa type: environment: el valor DT_TEST_URL es el nombre de una variable de entorno que contiene la URL. La documentación también permite escribirla directamente con type: value. Los nombres DT_TEST_URL y DT_TEST_PLATFORM_TOKEN son ejemplos elegidos para este curso.
URL de SaaS: la dirección de la plataforma
La URL esperada para las API de la plataforma tiene la forma https://<id-entorno>.apps.dynatrace.com. El código de Monaco rechaza una URL «clásica» cuando se autentica con un cliente OAuth o un token de plataforma, y su mensaje de error lo indica. Monaco deduce por sí mismo la dirección clásica sustituyendo .apps. por .live. y comprueba que responde. Si esa prueba falla, consulta la API de metadatos de la plataforma.
Consecuencia práctica: no escribas nunca la URL en .live.dynatrace.com en el manifiesto. Usa siempre la URL en .apps..
Autenticación: token de acceso, token de plataforma u OAuth
La sección auth admite tres métodos, y la documentación impone una regla: Monaco no permite escribir los secretos en el manifiesto. El campo name contiene el nombre de la variable de entorno que guarda el secreto, nunca el secreto en sí.
| Método | Claves del manifiesto | Sirve para |
|---|---|---|
| Token de acceso | token → name |
API de configuración y Settings (ámbitos v1 y v2) |
| Token de plataforma | platformToken → name |
API de la plataforma (workflows, documentos, buckets de Grail…), desde Monaco 2.24.0 |
| Cliente OAuth | oAuth → clientId y clientSecret → name |
Las mismas API de la plataforma |
Reglas de combinación: se puede asociar token con platformToken o con oAuth en un mismo entorno, pero no platformToken y oAuth a la vez. Los tokens de acceso y los tokens de plataforma no son intercambiables.
Ámbitos mínimos
Para un token de plataforma o un cliente OAuth, la documentación recomienda como mínimo app-engine:apps:run (metadatos de la plataforma), settings:objects:read, settings:objects:write y settings:schemas:read. Se añaden otros ámbitos según los recursos gestionados: automation:workflows:read y write, document:documents:*, storage:bucket-definitions:*, slo:slos:read y write, entre otros. Se aplica el principio de mínimo privilegio: concede solo lo que despliegan tus proyectos.
Para un token de acceso, la documentación cita como mínimo DataExport, ReadConfig, WriteConfig, settings.read y settings.write.
¿Qué elegir?
El token de plataforma es el más sencillo de poner en marcha: un solo secreto. El cliente OAuth pasa por Account Management (Identity & access management y luego OAuth clients); el secreto solo se muestra al crearlo, y las políticas IAM de los grupos del service user pueden restringir aún más los permisos. Ten en cuenta, por último, que el token de plataforma exige una versión reciente del CLI. El módulo sobre OAuth y los secretos profundiza en la gestión de secretos en CI.
Ejercicio práctico
Este ejercicio se hace en un entorno SaaS de pruebas (es posible una prueba gratuita). No se ejecutó ningún comando para la redacción: la salida exacta depende de tu versión.
Paso 1 — Instalar y comprobar
Sigue la secuencia de descarga anterior para tu sistema y ejecuta monaco version. Resultado esperado: el comando muestra la versión del CLI. Anótala.
Paso 2 — Crear el token o el cliente
Crea un token de plataforma (o un cliente OAuth) con los cuatro ámbitos mínimos citados arriba. Guarda el secreto en un gestor, no en un archivo del repositorio.
Paso 3 — Exportar las variables
export DT_TEST_URL="https://<id-environnement>.apps.dynatrace.com"
export DT_TEST_PLATFORM_TOKEN="<jeton de plateforme>"
Paso 4 — Escribir el manifiesto
Crea manifest.yaml como en la captura, además de una carpeta general para el proyecto. La carpeta puede quedar vacía por ahora; las configuraciones llegan en el módulo 4.
Paso 5 — Validar
Ejecuta monaco deploy manifest.yaml --dry-run. La documentación del indicador precisa que valida la estructura del manifiesto, de los proyectos y de las configuraciones, pero no el contenido de los JSON. No verificado: si este modo contacta con el entorno para probar las credenciales. Un error de autenticación suele señalar una URL en .live., una variable ausente o un ámbito que falta.
Cuestionario
- ¿Cuáles son las tres claves de primer nivel de un manifiesto? (a)
name,url,auth; (b)manifestVersion,projects,environmentGroups; (c)token,oAuth,platformToken. - ¿Qué contiene el campo
namebajoplatformToken? (a) el token; (b) el nombre de la variable de entorno que contiene el token; (c) el nombre del proyecto. - ¿Qué combinación está prohibida en un mismo entorno? (a)
tokenyoAuth; (b)tokenyplatformToken; (c)platformTokenyoAuth. - ¿Qué forma de URL hay que escribir para las API de la plataforma? (a)
…live.dynatrace.com; (b)…apps.dynatrace.com; (c) la dirección IP del servidor.
Respuestas
- (b): el manifiesto se compone de la versión, los proyectos y los grupos de entornos.
- (b): Monaco carga siempre los secretos desde el entorno, nunca desde el archivo.
- (c): un token de acceso puede acompañar a uno u otro, pero no a los dos métodos de plataforma a la vez.
- (b): Monaco deduce por sí mismo la dirección clásica a partir de la URL de la plataforma.
Para ir más lejos
- Dynatrace Monaco: la configuración como código, paso a paso
- Monaco o Terraform para la configuración de Dynatrace
- Los esquemas de la API de Dynatrace SaaS
- Documentación oficial: recursos de Monaco
- Repositorio Dynatrace Configuration as Code (Apache 2.0)
← Módulo 1: configuración como código en SaaS · Índice de la ruta · Módulo 3: exportación de Monaco SaaS →
Preguntas frecuentes
¿Hace falta un token de acceso además del token de plataforma?
Solo si tus proyectos usan API de configuración clásicas. Ambos se declaran uno junto al otro en auth, cada uno con su variable.
¿Se puede poner el token directamente en el manifiesto?
No. La documentación precisa que Monaco carga siempre las credenciales de autenticación desde variables de entorno.
¿Funciona Monaco en un contenedor?
La documentación oficial ofrece una imagen de contenedor; consulta su página de descarga para la referencia exacta.
Ya dispones de un CLI comprobado y de un manifiesto autenticado mediante variables de entorno. El módulo siguiente usa esta base para exportar una configuración existente.
span.observer es un blog independiente de la comunidad, no afiliado a Dynatrace LLC. Esta ruta no sustituye a las formaciones y certificaciones oficiales de Dynatrace University. Dynatrace es una marca de Dynatrace LLC. Comprueba siempre las funciones en la documentación oficial correspondiente a tu versión.