Saltar a contenido

Procedimientos de actualización/upgrade y de rollback

Por qué es importante mantenerse actualizado

Menos cambios incompatibles que asumir de una sola vez. Varias versiones han modificado elementos de los que dependen los despliegues más antiguos:

  • Rel-1.5 trasladó la configuración de los archivos a las variables de entorno y a docker-compose, y refactorizó los nombres de los campos de la base de datos.
  • Rel-1.12 añadió el Customer (Network) ID. LTI_customer_id es ahora un parámetro obligatorio del agente, y las preguntas frecuentes incluyen «customerID is required» como error de la API.
  • Rel-2.5 modificó la disposición de los datos del MCP, de modo que las carpetas certs y data se encuentran ahora en mcp/. También introdujo las licencias acumuladas y una contraseña aleatoria opcional para el analyzer.

Un sitio que se salta varias versiones asume todo esto en una sola ventana de mantenimiento y tiene más que diagnosticar en caso de fallo.

Seguridad y licencias.

  • Rel-2.1 ejecutó pruebas de vulnerabilidad, actualizó los componentes de código abierto y añadió API de descubrimiento seguras.
  • Rel-2.5 añadió contraseñas aleatorias para el analyzer.
  • Rel-2.5 añadió el mecanismo de caducidad de licencias de los agentes, con avisos en Grafana y un periodo de gracia antes de la detención de los datos.
  • La stack incluye ahora Grafana 12.4.2, InfluxDB 2.8.0, Kafka 8.2.0 y Telegraf 1.38.

Precisión y fiabilidad de las mediciones. Las correcciones recientes afectan directamente a la calidad de los datos:

  • Rel-2.4.1 corrigió sockets TCP persistentes que interrumpían las mediciones LIFBE durante aproximadamente una hora.
  • Rel-2.4.2 corrigió la temporización de iPerf3 multiperfil.
  • Rel-2.5 corrigió el registro de iPerf, que solo capturaba el caudal del primer agente cuando dos agentes enviaban al mismo tiempo.
  • Rel-2.5 corrigió las mediciones iPerf UDP retrasadas.
  • Rel-2.5 envía los valores PCI para 4G, y no solo para 5G.

Funcionalidades que llegan progresivamente.

  • Rel-2.3: servidor MCP, nuevos endpoints OpenAPI, compatibilidad con IPv6 para las conexiones del agente al reflector.
  • Rel-2.4: mapas de calor mejorados, herramientas de resolución de problemas, compatibilidad con XR-90.
  • Rel-2.5: panel de control de interrupciones, percentiles en la vista de latencia detallada.

Cada versión aporta nuevos paneles de control, API y compatibilidad de hardware, y una diferencia mayor significa más trabajo de adopción de una sola vez.

Soporte. Los clientes con las versiones actuales son los más fáciles de diagnosticar y corregir, y la documentación siempre describe el comportamiento más reciente.

¿Cómo puedo actualizar mi versión del Analyzer, del Reflector y de los QoS Agents?

Cuando haya una nueva versión disponible (consulte las Notas de la versión), actualice los componentes en este orden:

  1. Analyzer
  2. Reflector
  3. QoS Agents

Verifique cada componente antes de pasar al siguiente. Si una verificación falla, siga el procedimiento de rollback de ese componente.

Si tiene paneles de control personalizados, póngase en contacto con su proveedor de LatenceTech antes de actualizar el Analyzer.

Antes de empezar

  • Planifique una ventana de mantenimiento. Las mediciones no se almacenan durante la copia de seguridad o la actualización del Analyzer.
  • Tenga a mano todas sus claves de licencia actuales.
  • Ejecute la actualización del Analyzer como el usuario que instaló el Analyzer, desde el directorio home de ese usuario, que debe contener la carpeta lti_analyzer/. InfluxDB y Grafana se ejecutan con el ID de ese usuario y sus carpetas de datos le pertenecen; otro usuario provocaría errores de permisos.
  • Si utiliza una contraseña aleatoria para el analyzer, debe tener al menos 8 caracteres. Está guardada en ~/.saved_lti_password en el host del Analyzer y definida como LTI_SERVICE_KEY en sus QoS Agents.
  • Anote los siguientes valores de lti_analyzer/docker-compose.yml: ADMIN_KEY, MCP_TOKEN, LTI_license_key, LTI_password y LTI_PERCENTILE_FILTER o LTI_percentile_filter. El script de actualización en línea los restaura automáticamente, pero los necesita para el procedimiento sin conexión y para verificar el resultado.
  • Asegúrese de que cada host dispone de suficiente espacio libre en disco para la copia de seguridad. Los archivos de imágenes pueden ocupar varios GB.

1) Hacer una copia de seguridad de su sistema

La copia de seguridad se almacena en ~/lti-rollback/. No utilice ~/lti-backup/: el script de actualización del Analyzer escribe en esa carpeta y sobrescribe su contenido.

Una instantánea de la máquina virtual tomada antes de la actualización también constituye una copia de seguridad válida y permite un rollback más rápido.

Host del Analyzer

El Analyzer conserva sus datos en carpetas dentro de ~/lti_analyzer/ (influxdb/data, grafana/grafana, mcp/certs y mcp/data), por lo que la copia de seguridad siguiente las cubre todas. También guarda dos archivos de su directorio home: ~/.cached_lti_license_key, que está montado en el contenedor de la API, y ~/.saved_lti_password, que solo existe si utiliza una contraseña aleatoria.

Cree la copia de seguridad:

mkdir -p ~/lti-rollback/config
cp ~/.saved_lti_password ~/lti-rollback/config/ 2>/dev/null
cp ~/.cached_lti_license_key ~/lti-rollback/config/ 2>/dev/null

# Stop the whole Analyzer so that the InfluxDB and Grafana files are consistent
docker compose -f ~/lti_analyzer/docker-compose.yml stop

# Save the InfluxDB data
sudo tar -czf ~/lti-rollback/influxdb-data.tar.gz -C ~ lti_analyzer/influxdb/data

# Save the rest of the Analyzer folder (docker-compose.yml, Grafana data, mcp, certs, data, ...)
sudo tar -cf ~/lti-rollback/lti_analyzer-config.tar --exclude='lti_analyzer/influxdb/data' -C ~ lti_analyzer

# Start the Analyzer again
docker compose -f ~/lti_analyzer/docker-compose.yml start

# Save the current container images, to be able to roll back without downloading
docker images --format '{{.Repository}}:{{.Tag}}' | grep -v '<none>' | xargs docker save -o ~/lti-rollback/images-pre-upgrade.tar

Verifique la copia de seguridad antes de continuar:

ls -lhA ~/lti-rollback ~/lti-rollback/config
sudo tar -tzf ~/lti-rollback/influxdb-data.tar.gz | head -5
sudo tar -tf ~/lti-rollback/lti_analyzer-config.tar | grep -m3 'lti_analyzer/grafana/grafana'

Cada comando debe mostrar algo, y config/ debe contener .cached_lti_license_key (y .saved_lti_password si utiliza una contraseña aleatoria).

# The backup contains passwords and keys: restrict access to it
sudo chmod -R go-rwx ~/lti-rollback

Host del Reflector

Ejecute desde el directorio que contiene lti_reflector.yml:

mkdir -p ~/lti-rollback
cp lti_reflector.yml ~/lti-rollback/lti_reflector.yml.pre-upgrade
docker save -o ~/lti-rollback/reflector-image.tar registry.latence.ca/software/reflector

Hosts de los QoS Agents

Ejecute desde el directorio que contiene lti_qos-agent.yml:

mkdir -p ~/lti-rollback
cp lti_qos-agent.yml ~/lti-rollback/lti_qos-agent.yml.pre-upgrade
docker save -o ~/lti-rollback/qos-agent-image.tar registry.latence.ca/software/qos-agent

2) Actualizar el Analyzer

No tiene paneles de control personalizados (instalación en línea):

Vaya al directorio que contiene la carpeta lti_analyzer/ (su directorio home), descargue el script y ejecútelo con sudo:

cd ~
wget https://api.latence.ca/software/update.sh

sudo bash update.sh

El script pregunta si desea hacer una copia de seguridad de sus datos de InfluxDB. Responda y para conservar sus datos históricos. Si responde n, el Analyzer se reinstala con una base de datos vacía.

A continuación, el script detiene y elimina sus contenedores e imágenes actuales del Analyzer, reinstala el Analyzer más reciente, vuelve a colocar sus datos de InfluxDB y restaura automáticamente sus claves de licencia, el filtro de percentil, la contraseña del analyzer, ADMIN_KEY, MCP_TOKEN y los datos del MCP.

Como el script ejecuta el instalador estándar, también se le harán dos preguntas:

  • Filtro de percentil 95 (true/false): responda con su ajuste actual.
  • Contraseña aleatoria (true/false): esta pregunta solo se hace si no utiliza ya una contraseña aleatoria (es decir, si ~/.saved_lti_password no existe). Responda false para conservar su contraseña actual. Si responde true, se genera y se aplica una nueva contraseña aleatoria, y deberá definirla como LTI_SERVICE_KEY en cada QoS Agent; de lo contrario, dejarán de enviar datos.

El instalador no pide ninguna clave de licencia durante una actualización: reutiliza la clave guardada en ~/.cached_lti_license_key. Al final, espera a la verificación de la licencia, lo que puede tardar unos minutos.

Notas:

  • No interrumpa el script. Si se interrumpe o falla a mitad de camino, no lo vuelva a ejecutar. Siga el procedimiento de rollback.
  • Si el script se queda en «Waiting for License logs» durante más de unos minutos, consulte docker logs lti_analyzer-influx-writer-1. Si la licencia indica 0 agentes autorizados, el script pide una clave de licencia válida.
  • La copia de seguridad realizada por el script (en ~/lti-backup/) solo contiene los datos de InfluxDB y dos archivos de configuración. No es una copia de seguridad para rollback: la copia de seguridad del paso 1 sigue siendo necesaria.
  • El script muestra «Update completed successfully» aunque haya fallado algún paso. Realice siempre las verificaciones que se indican a continuación.

Tiene paneles de control personalizados:

Póngase en contacto con su proveedor de LatenceTech antes de la actualización.

Instalación sin conexión:

Requisitos previos:

  • Disponer del nuevo Analyzer_offline.zip. Puede descargarse con wget https://api.latence.ca/software/Analyzer_offline.zip u obtenerse en una memoria USB a través de LatenceTech.
  • Ejecute todos los comandos desde el directorio que contiene tanto lti_analyzer/ como Analyzer_offline.zip. En este ejemplo, lti_analyzer/ está en su directorio home (~/); adapte los comandos a su ubicación.
  • Paso 1 (copia de seguridad) completado.

2a) Eliminar los contenedores

Advertencia: este comando elimina todos los contenedores e imágenes del host. Ejecútelo solo en un host dedicado al Analyzer.

# Delete containers and images
docker stop $(docker ps -q) && docker rm $(docker ps -a -q) && docker rmi $(docker images -q) && docker system prune -af

# Cleaning up
sudo rm -rf ~/lti_analyzer/ ~/lti_analyzer.launch.log

2b) Reinstalación

# Unzip
unzip Analyzer_offline.zip 2>&1

# Go in the folder
cd Analyzer_offline/

# Execute script
bash install-run-analyzer-offline.sh

# Go back to the previous directory
cd ..

2c) Volver a colocar sus datos

# Stop containers influxdb and influx-writer
docker stop lti_analyzer-influxdb-1
docker stop lti_analyzer-influx-writer-1

# Extract influxdb data
sudo tar -xf ~/lti-rollback/influxdb-data.tar.gz -C ~

# Restarting influxdb and influx-writer
docker start lti_analyzer-influxdb-1
docker start lti_analyzer-influx-writer-1

# Place back the MCP server data, certs and data folders (the ones that exist in your backup)
for d in mcp certs data; do sudo tar -xf ~/lti-rollback/lti_analyzer-config.tar -C ~ lti_analyzer/$d 2>/dev/null; done

Si certs/ o data/ existen en la raíz de lti_analyzer/, muévalas a la nueva estructura de carpetas mcp/:

mkdir -p ~/lti_analyzer/mcp
sudo mv ~/lti_analyzer/certs ~/lti_analyzer/mcp/ 2>/dev/null
sudo mv ~/lti_analyzer/data ~/lti_analyzer/mcp/ 2>/dev/null

2d) Restaurar la configuración

# Restore home config files (if backed up)
cp ~/lti-rollback/config/.saved_lti_password ~/.saved_lti_password 2>/dev/null
chmod 600 ~/.saved_lti_password 2>/dev/null
cp ~/lti-rollback/config/.cached_lti_license_key ~/.cached_lti_license_key 2>/dev/null

Edite lti_analyzer/docker-compose.yml y vuelva a introducir los valores que anotó antes de la actualización (ADMIN_KEY, MCP_TOKEN, LTI_license_key, LTI_password, filtro de percentil).

Si tenía una contraseña para el analyzer, vuelva a aplicarla a Grafana e InfluxDB (sustituya YOUR_PASSWORD):

GRAFANA_ID=$(docker ps --format "{{.ID}} {{.Image}}" | grep grafana | awk '{print $1}')
INFLUX_ID=$(docker ps --format "{{.ID}} {{.Image}}" | grep influxdb | awk '{print $1}')
docker exec -u root $GRAFANA_ID grafana-cli admin reset-admin-password YOUR_PASSWORD
docker exec $INFLUX_ID influx user password --name LatenceTech --password YOUR_PASSWORD --host http://localhost:8086

2e) Reiniciar los servicios

# Restart influx-writer to apply license key
docker stop lti_analyzer-influx-writer-1
docker start lti_analyzer-influx-writer-1

Si ha restaurado una contraseña, vuelva a lanzar todos los servicios:

docker compose -f lti_analyzer/docker-compose.yml up -d

Si solo ha restaurado ADMIN_KEY o MCP_TOKEN, reinicie los servicios del MCP:

docker compose -f lti_analyzer/docker-compose.yml restart latencetech_mcp chatbot_api

Verificar el Analyzer antes de continuar

  • Todos los contenedores del Analyzer están en ejecución (docker ps).
  • Los paneles de control se cargan en http://YOUR_ANALYZER_HOST_IP:12021.
  • Se muestran sus datos históricos.
  • El estado de la licencia y la fecha de caducidad se muestran correctamente.

Si alguna de estas verificaciones falla, siga el procedimiento de rollback.

3) Actualizar el Reflector

Para el reflector, puede utilizar el script de actualización que se indica aquí:

wget https://api.latence.ca/software/update_reflector.sh

bash update_reflector.sh

O puede hacerlo manualmente siguiendo los pasos que se indican a continuación:

docker stop lti_reflector && docker rm lti_reflector && docker rmi registry.latence.ca/software/reflector

Elimine la versión anterior del archivo de instalación:

rm lti_reflector.yml

A continuación, puede volver a descargar el archivo yaml aquí y editarlo con su clave de licencia y su ID:

wget https://api.latence.ca/software/lti_reflector.yml

Vuelva a lanzar el Reflector:

docker compose -f lti_reflector.yml up -d

Instalación sin conexión: descargue Reflector_offline.zip (wget https://api.latence.ca/software/Reflector_offline.zip) u obténgalo de la memoria USB, detenga y elimine el contenedor anterior como se ha indicado, descomprima el archivo y ejecute el script de la carpeta con bash. El script crea la nueva imagen. A continuación, despliegue el contenedor rellenando lti_reflector.yml como se explica en la documentación.

Verificar el Reflector antes de continuar

docker compose -f lti_reflector.yml logs

Los registros no muestran ningún error.

4) Actualizar los QoS Agents

Recomendamos actualizar primero un agente, verificarlo y, después, actualizar los demás.

Para actualizar el QoS Agent a la última versión, debe detener y eliminar las imágenes de los dockers en ejecución con el siguiente comando:

docker stop lti_qos-agent && docker rm lti_qos-agent && docker rmi registry.latence.ca/software/qos-agent

Elimine la versión anterior del archivo de instalación:

rm lti_qos-agent.yml

A continuación, puede volver a descargar el archivo yaml aquí y editarlo con sus valores:

wget https://api.latence.ca/software/lti_qos-agent.yml

Si utiliza una contraseña aleatoria para el analyzer, defina LTI_SERVICE_KEY con la contraseña del analyzer. Para no olvidar ningún valor, compare el nuevo archivo con su copia de seguridad:

diff ~/lti-rollback/lti_qos-agent.yml.pre-upgrade lti_qos-agent.yml

Después, ejecute lo siguiente para descargar las nuevas imágenes.

docker compose -f lti_qos-agent.yml up -d

Otras formas de actualizar un agente:

  • QoS Agent Management Dashboard: si está instalado en el host del agente, utilice Docker Management > Update para descargar las últimas imágenes de contenedor y reiniciar los servicios.
  • Instalación sin conexión: descargue Agent_offline.zip (wget https://api.latence.ca/software/Agent_offline.zip) u obténgalo de la memoria USB, detenga y elimine el contenedor anterior como se ha indicado, descomprima el archivo y ejecute el script de la carpeta con bash. El script crea la nueva imagen. A continuación, despliegue el contenedor rellenando lti_qos-agent.yml como se explica en la documentación.
  • Agentes Cradlepoint y SDK: siga las páginas Despliegue en Cradlepoint y Despliegue del QoS Agent SDK.

Verificar el QoS Agent

docker compose -f lti_qos-agent.yml logs

Los registros no muestran ningún error y los datos del agente aparecen en los paneles de control con su ID de agente.

5) Verificación final

  • Todos los agentes aparecen en los paneles de control y envían datos.
  • El Analyzer informa del estado de licencia esperado.
  • Conserve ~/lti-rollback/ en cada host hasta que el sistema haya funcionado con normalidad durante un ciclo completo.

¿Cuál es el procedimiento de rollback en caso de fallo de la actualización?

Usted es responsable de mantener un procedimiento de rollback. Recomendamos encarecidamente hacer una copia de seguridad del sistema antes de la actualización, utilizando el paso 1 del procedimiento de actualización. El procedimiento siguiente restaura el sistema a partir de esa copia de seguridad y debe realizarse en el orden inverso al de la actualización: QoS Agents, después Reflector y, por último, Analyzer.

Cada componente puede revertirse de forma individual:

  • Si falla la actualización del Analyzer, revierta solo el Analyzer (todavía no se ha actualizado nada más).
  • Si falla la actualización del Reflector, revierta solo el Reflector.
  • Si falla la actualización de un QoS Agent, revierta solo los agentes afectados.
  • Si decide abandonar toda la actualización, revierta en este orden: QoS Agents, Reflector, Analyzer.

No ejecute docker compose pull, los scripts de actualización ni el botón Update del QoS Agent Management Dashboard durante un rollback. Volverían a descargar la nueva versión.

Si el script de actualización del Analyzer falló a mitad de camino, no lo vuelva a ejecutar. Haga primero el rollback.

Requisitos previos

  • La carpeta ~/lti-rollback/ creada en el paso 1 del procedimiento de actualización, en cada host. Esta carpeta es distinta de ~/lti-backup/, que utiliza el script de actualización del Analyzer y que no se utiliza para el rollback.
  • Los archivos de imágenes guardados (images-pre-upgrade.tar, reflector-image.tar, qos-agent-image.tar).

1) Rollback de los QoS Agents

En cada host de agente, desde el directorio que contiene lti_qos-agent.yml:

# Remove the new version
docker stop lti_qos-agent && docker rm lti_qos-agent
docker rmi registry.latence.ca/software/qos-agent

# Restore the previous image and configuration file
docker load -i ~/lti-rollback/qos-agent-image.tar
cp ~/lti-rollback/lti_qos-agent.yml.pre-upgrade lti_qos-agent.yml

# Start the previous version without downloading anything
docker compose -f lti_qos-agent.yml up -d --pull never

Si el QoS Agent Management Dashboard está instalado, también puede restaurar una versión de configuración anterior desde su Agent Configuration Editor. La imagen del contenedor en sí debe restaurarse siempre con los comandos anteriores.

2) Rollback del Reflector

En el host del reflector, desde el directorio que contiene lti_reflector.yml:

# Remove the new version
docker stop lti_reflector && docker rm lti_reflector
docker rmi registry.latence.ca/software/reflector

# Restore the previous image and configuration file
docker load -i ~/lti-rollback/reflector-image.tar
cp ~/lti-rollback/lti_reflector.yml.pre-upgrade lti_reflector.yml

# Start the previous version without downloading anything
docker compose -f lti_reflector.yml up -d --pull never

3) Rollback del Analyzer

La copia de seguridad contiene la totalidad de la carpeta lti_analyzer/ (configuración, datos de Grafana, datos del MCP, certificados) y los datos de InfluxDB. Si el script de actualización del Analyzer falló a mitad de camino, puede haber dejado copias de las carpetas mcp, certs y data en su directorio home. Ya forman parte de la copia de seguridad, y puede eliminarlas una vez verificado el rollback.

Ejecute los comandos docker compose que se indican a continuación como el usuario que instaló el Analyzer, sin sudo. El archivo compose monta ${HOME}/.cached_lti_license_key, y con otro directorio home Docker crearía una carpeta en lugar de ese archivo.

# Stop and remove the new version (skip the first command if the folder no longer exists)
docker compose -f ~/lti_analyzer/docker-compose.yml down
docker ps -a --filter name=lti_analyzer -q | xargs -r docker rm -f
sudo rm -rf ~/lti_analyzer ~/lti_analyzer.launch.log

# Restore the previous Analyzer folder (docker-compose.yml, Grafana data, mcp, certs, ...) and images
sudo tar -xf ~/lti-rollback/lti_analyzer-config.tar -C ~
docker load -i ~/lti-rollback/images-pre-upgrade.tar

# Restore the InfluxDB data saved before the upgrade
sudo tar -xf ~/lti-rollback/influxdb-data.tar.gz -C ~

# Restore home config files (before starting the Analyzer: the license key file is mounted into the API container)
cp ~/lti-rollback/config/.saved_lti_password ~/.saved_lti_password 2>/dev/null
chmod 600 ~/.saved_lti_password 2>/dev/null
cp ~/lti-rollback/config/.cached_lti_license_key ~/.cached_lti_license_key 2>/dev/null

# Start the previous version without downloading anything
docker compose -f ~/lti_analyzer/docker-compose.yml up -d --pull never

# Restart influx-writer to apply the license key
docker stop lti_analyzer-influx-writer-1
docker start lti_analyzer-influx-writer-1

Si no puede iniciar sesión con su contraseña anterior del analyzer, vuelva a aplicarla a Grafana e InfluxDB (sustituya YOUR_PASSWORD):

GRAFANA_ID=$(docker ps --format "{{.ID}} {{.Image}}" | grep grafana | awk '{print $1}')
INFLUX_ID=$(docker ps --format "{{.ID}} {{.Image}}" | grep influxdb | awk '{print $1}')
docker exec -u root $GRAFANA_ID grafana-cli admin reset-admin-password YOUR_PASSWORD
docker exec $INFLUX_ID influx user password --name LatenceTech --password YOUR_PASSWORD --host http://localhost:8086

Si no guardó las imágenes de los contenedores

Reinstale la versión anterior con el mismo método que utilizó para la instalación y, después, restaure sus datos y su configuración desde ~/lti-rollback/:

  • Instalaciones sin conexión: utilice los Analyzer_offline.zip, Reflector_offline.zip y Agent_offline.zip anteriores, y siga los pasos 2c a 2e de la actualización del Analyzer sin conexión.
  • Instalaciones en línea: los scripts en línea instalan siempre la última versión. Póngase en contacto con su proveedor de LatenceTech para obtener la versión anterior.

Después del rollback

  • Abra los paneles de control en http://YOUR_ANALYZER_HOST_IP:12021 y confirme que se muestran los datos históricos y que sus paneles de control y usuarios están presentes.
  • Confirme que cada agente envía datos, mediante los paneles de control y docker compose -f lti_qos-agent.yml logs.
  • Si utiliza una contraseña aleatoria para el analyzer, confirme que LTI_SERVICE_KEY en cada agente corresponde a la contraseña restaurada.
  • Las mediciones recopiladas entre la actualización y el rollback no forman parte de la base de datos restaurada.
  • Conserve ~/lti-rollback/ hasta que el sistema haya funcionado con normalidad durante un ciclo completo.

Si el rollback no restaura un sistema operativo, envíe datos al soporte y abra un ticket con el equipo de soporte de LatenceTech.