Redirigir OneAgent a SaaS: oneagentctl sin reinstalar

Redirigir OneAgent a SaaS con oneagentctl: obtén el token, cambia el servidor, reinicia y verifica cada host sin reinstalar el agente.
Rediriger OneAgent vers SaaS : oneagentctl sans réinstaller

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 InstallerDownload para leer la información de conexión (o, con un cliente OAuth o un platform token, el scope fleet-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.

Estructura JSON de la respuesta connectioninfo de la API de despliegue: communicationEndpoints, formattedCommunicationEndpoints, tenantToken y tenantUUID

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:

Comando oneagentctl en Linux con set-server, set-tenant, set-tenant-token y restart-service
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.

Comandos oneagentctl.exe get-server, get-tenant y get-tenant-token ejecutados desde una consola de administrador de Windows
  1. --get-server muestra 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.
  2. --get-tenant muestra el identificador del entorno: debe corresponder al entorno SaaS.
  3. --get-tenant-token muestra el token definido. No copies esta salida en un ticket ni en un registro compartido.
  4. 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-server sustituye 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.

Total
0
Shares
Leave a Reply

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

Previous Post
Agent SRE AIOps : ce que promettent les plateformes

Agente SRE AIOps: lo que prometen las plataformas

Next Post
eBPF sans sidecar : service mesh, Cilium et OpenTelemetry, ce qui change

eBPF sin sidecar: service mesh, Cilium y OpenTelemetry, qué cambia

Related Posts