Para redirigir OneAgent a SaaS sin reinstalarlo, la documentación de Dynatrace prevé la herramienta de línea de comandos oneagentctl: cambia el punto de comunicación de un agente ya instalado. Para un equipo SRE que migra de Managed a SaaS, es la forma menos intrusiva de mover un parque de hosts, siempre que se sepa qué cambia realmente y cómo comprobar el resultado.
El problema es habitual. Los hosts funcionan, las aplicaciones están instrumentadas y nadie quiere repetir un despliegue completo en cientos de máquinas solo para cambiar un destino. Esta guía complementa el plan global de migración de Managed a SaaS y la recuperación de la configuración descrita en Monaco de Managed a SaaS: aquí solo se tratan los agentes.
El contenido se basa en la documentación oficial de oneagentctl (versiones SaaS y Managed de la página) y en la referencia de la API de despliegue. Vale para Dynatrace Managed (origen) y Dynatrace SaaS (destino).
Redirigir OneAgent a SaaS: qué debes saber antes
Según la documentación, oneagentctl permite configurar OneAgent a nivel de un host individual. El parámetro --set-server define el punto de comunicación: se indica una dirección o un nombre, seguido del sufijo /communication. El punto puede ser un servidor Dynatrace, un clúster Managed o un ActiveGate.
Tres parámetros van juntos para redirigir a otro entorno:
--set-server: el nuevo punto de comunicación;--set-tenant: el identificador del entorno. La documentación precisa que, por defecto, ya es correcto; aquí hay que cambiarlo porque el entorno de destino es distinto. Se usa siempre con--set-tenant-token;--set-tenant-token: el token que autentica la comunicación con el punto definido (no lo confundas con un token de API).
Los parámetros set requieren reiniciar el servicio OneAgent. Según la misma página, en algunos casos estos ajustes exigen también reiniciar las aplicaciones monitorizadas. El parámetro --restart-service reinicia el servicio en el mismo comando. Se pueden combinar varios parámetros set en un solo comando.
Requisitos previos
- Un entorno Dynatrace SaaS accesible desde los hosts por HTTPS saliente (directamente o a través de un ActiveGate).
- Acceso de root en Linux o de administrador en Windows: la documentación lo exige para ejecutar
oneagentctl. - Un token de API de SaaS con el scope
InstallerDownloadpara leer la información de conexión (o, con un cliente OAuth o un platform token, el scopefleet-management:oneagent.connection-info:read). - Un inventario de hosts por oleada, como en la guía de migración. Un host de prueba para la primera oleada.
Paso 1: obtener la información de conexión de SaaS
La referencia de la API de despliegue describe la petición GET https://{id-environnement}.live.dynatrace.com/api/v1/deployment/installer/agent/connectioninfo. La respuesta es un JSON de cuatro campos: communicationEndpoints (lista ordenada por prioridad decreciente), formattedCommunicationEndpoints, tenantToken y tenantUUID. Son exactamente los valores que hay que pasar a oneagentctl.

El parámetro opcional networkZone devuelve los endpoints de una network zone concreta; version (formato 1.221) solicita el formato de lista óptimo para la versión de agente indicada. Trata el tenantToken como un secreto: guárdalo en tu gestor de secretos, no en un repositorio Git.
Paso 2: redirigir un host Linux
En Linux, la herramienta está por defecto en /opt/dynatrace/oneagent/agent/tools (o en <INSTALL_PATH>/agent/tools si la instalación se personalizó). El comando de redirección se escribe así, con valores de ejemplo:

cd /opt/dynatrace/oneagent/agent/tools
sudo ./oneagentctl --set-server="https://<id-env>.live.dynatrace.com/communication" \
--set-tenant=<id-env> \
--set-tenant-token=<tenant-token> \
--restart-service
Si los hosts pasan por un ActiveGate, el punto de comunicación es el del ActiveGate, con su puerto: la documentación da el ejemplo https://<activegate-endpoint>:9999/communication. Para varios puntos, la documentación indica separarlos con punto y coma y poner el conjunto entre comillas. Los problemas de puerto se tratan en OneAgent y ActiveGate en el puerto 9999.
En Windows, la sintaxis es la misma con .\oneagentctl.exe, ejecutado desde una consola de administrador; la herramienta está por defecto en %PROGRAMFILES%\dynatrace\oneagent\agent\tools. Sin permisos, la documentación señala que Windows muestra una ventana de control de cuentas de usuario y que el comando falla.
Paso 3: reiniciar las aplicaciones si es necesario
Reiniciar el servicio no siempre basta. La documentación menciona que estos parámetros requieren, según los casos, reiniciar las aplicaciones monitorizadas. Para un proceso ya inyectado, planifica ese reinicio con el equipo de la aplicación, fuera de las horas punta. Este punto pesa en el MTTR: una aplicación sin reiniciar puede seguir sin aparecer en el entorno de destino aunque el host sí sea visible.
Cómo comprobar que funciona
Los parámetros get sirven para leer el estado. No modifican nada y son adecuados para un control automatizado tras cada oleada.

--get-servermuestra los endpoints a los que OneAgent envía sus datos. Desde OneAgent 1.207, la salida agrupa entre llaves los endpoints de la misma prioridad, ordenados por prioridad de conexión, y un asterisco señala el que se usa en ese momento.--get-tenantmuestra el identificador del entorno: debe corresponder al entorno SaaS.--get-tenant-tokenmuestra el token definido. No copies esta salida en un ticket ni en un registro compartido.- En el entorno SaaS, el host debe aparecer; compara el número de hosts visibles con el inventario de la oleada (criterio de éxito medible, por ejemplo 100 % en menos de 30 minutos).
Para la CI o una herramienta de despliegue, estas tres lecturas forman una prueba sencilla: un host cuyo servidor o tenant no coincide con el destino es un host sin migrar.
Buenas prácticas y errores frecuentes
- Primero una prueba: redirige un host no crítico, comprueba y amplía por oleadas con un plan de vuelta atrás (el mismo comando, con los valores de Managed).
- Un solo entorno por agente:
--set-serversustituye el punto de comunicación; no cuentes con un doble envío para comparar. Mantén hosts testigo en Managed. - Secretos: el token de tenant circula por tus scripts. Inyéctalo desde un gestor de secretos.
- Cortafuegos: abre los flujos hacia SaaS o el ActiveGate antes de la oleada, no durante.
- Identificadores de entidades: a confirmar en el host de prueba, ya que todo lo que referencia un identificador fijo (dashboards, scripts) debe revisarse. Este punto no se detalla en la página de
oneagentctl. - OpenTelemetry: los exportadores OTLP y los Collectors apuntan al entorno, no a OneAgent; sus URL y tokens se cambian por separado (ver OneAgent y OpenTelemetry: evitar duplicados).
Para la automatización a gran escala, una reinstalación limpia desde tu herramienta de despliegue sigue siendo una opción, y la elección del modo de instalación depende de tu contexto; las bases del despliegue se describen en OneAgent en Linux.
Preguntas frecuentes
¿Hay que reinstalar OneAgent para pasar de Managed a SaaS?
No necesariamente: oneagentctl cambia el punto de comunicación, el entorno y el token de un agente instalado. Comprueba la versión del agente y prueba en un host antes de generalizar.
¿Dónde encuentro el token de tenant y la URL de comunicación?
En la respuesta de la API de despliegue connectioninfo: tenantToken, tenantUUID y la lista communicationEndpoints. Exige el scope InstallerDownload.
¿Hay que reiniciar las aplicaciones?
La documentación indica que los parámetros set requieren reiniciar el servicio OneAgent y, en algunos casos, las aplicaciones monitorizadas. Inclúyelo en el calendario de la oleada.
Conclusión
Redirigir OneAgent a SaaS se resume en un comando: --set-server, --set-tenant, --set-tenant-token y reinicio. El trabajo real está alrededor: obtener los valores correctos, avanzar por oleadas, verificar con los parámetros get y conservar una vuelta atrás.
span.observer es un blog independiente de la comunidad, no afiliado a Dynatrace LLC. Dynatrace es una marca de Dynatrace LLC. Los parámetros y versiones evolucionan: comprueba siempre los valores en la documentación oficial de oneagentctl y de la API de despliegue.