Saltar al contenido principal

Actualizando

Aquí describiremos los pasos recomendados para actualizar una instalación de Horizon 2.x.

Requisitos previos​

  • Una implementación existente de Horizon que consiste en una o más instancias de Horizon.
  • Todas las instancias deben estar en la misma versión 2.x para comenzar.
  • Si la instalación es bare-metal, tienes acceso a la terminal o a la línea de comandos en cada host que tenga una instalación de Horizon.
  • Si se implementó directamente en el demonio de Docker, tienes acceso a la línea de comandos en el host que está ejecutando el demonio de Docker.
  • Si se implementó en Kubernetes con un gráfico de Helm, tienes herramientas de línea de comandos kubectl y helm en tu estación de trabajo y un inicio de sesión de usuario con los niveles de acceso apropiados para cambiar recursos en el espacio de nombres de destino de la implementación de Horizon en el clúster.

Evaluar la instalación actual​

  • Identifica la lista de todas las instancias de Horizon que necesitan ser actualizadas.

    • Instalaciones bare-metal: la lista de hosts es gestionada por ti.

    • Despliegues en demonios de Docker: la lista de hosts y contenedores en ejecución es gestionada por ti.

    • Despliegues en Kubernetes: obtén la lista de pods que se desplegaron desde tu instalación previa de Helm, tendrán una anotación para release=tu_nombre_de_instalación_helm_horizon:

      kubectl get pods -l release=your_helm_horizon_installation_name -n <your_horizon_namespace>

  • Identifica tu versión actual de software de Horizon:

    • Obtén acceso a la línea de comandos del sistema operativo de cada instancia de Horizon:
      • Para instalaciones bare-metal, esto típicamente es ssh en Linux o PowerShell en Windows.
      • Despliegues en el demonio de Docker, usa docker exec -it <containerid> /bin/bash
      • Para despliegues en Kubernetes, usa kubectl exec -it <pod_name> -n <horizon_namespace> -- /bin/bash
    • En la línea de comandos de cada instancia, ejecuta stellar-horizon version

  • Todas las instancias deben reportar la misma versión; si no, el sistema puede ser inconsistente, usa esta actualización como oportunidad para establecer consistencia y ponerlas todas en la misma versión.

Determina la versión objetivo para la actualización​

Ahora que sabes tu versión actual de Horizon, visita Horizon Releases y elige la próxima versión superior a tu versión actual para actualizar. Sigue los pasos recomendados por GitHub para comparar versiones, haz clic en el desplegable Compare de la versión elegida, y luego selecciona tu versión actual y GH mostrará las diferencias entre versiones, selecciona la pestaña Files changed, y ve a services/horizon/CHANGELOG.md, se resaltarán las nuevas notas de publicación para los cambios que han ocurrido entre tu versión actual y la nueva versión que seleccionaste. Revisa esto y busca cualquier sección de Breaking Changes, State Rebuild y DB Schema Migration para consideración, ya que las dos últimas también mencionarán el tiempo esperado para que se apliquen la reconstrucción de estado o la migración de la base de datos respectivamente.

Instalar la nueva versión​

Ahora que has identificado la nueva versión y eres consciente de los posibles impactos de actualizar a una nueva versión basada en las notas de publicación, tales como reconstrucciones de estado y migraciones de base de datos, estás informado y listo para proceder con la actualización.

Actualizar implementaciones en producción debería aprovechar una implementación secundaria, de respaldo activo, también conocida como modelo azul/verde y realizar la actualización en la implementación inactiva primero. Esto evitará el tiempo de inactividad del sistema para tus usuarios externos, ya que la actualización tiene lugar en la implementación inactiva.

Una buena estrategia para actualizar Horizon y aplicable a implementaciones de una o múltiples instancias: apaga todas las instancias, instala la nueva versión de Horizon en una de las instancias que están ingiriendo primero. La razón es que el software de Horizon solo iniciará acciones de State Rebuild y DB Schema Migration relacionadas con una actualización en una instancia que detecta que la ingestión ha sido habilitada con el parámetro de configuración, INGEST=true. Esto reduce la complejidad para ti durante la actualización, ya que solo necesitas enfocarte en una instancia y evita procesos concurrentes de ingestión de Horizon intentando la misma actualización en la base de datos.

  • En instalaciones bare-metal, detén el proceso de Horizon en todas las instancias primero, luego accede a una instancia que está configurada para la ingestión, y usa el administrador de paquetes apt en Linux.

    sudo apt update
    sudo apt install stellar-horizon=new_horizon_debian_pkg_version

    Reinicia Horizon utilizando la configuración ya aplicada, pero incluye la variable de entorno APPLY_MIGRATIONS=true, esto hará que Horizon ejecute automáticamente cualquier migración de base de datos que detecte que es necesaria.

  • En despliegues en demonios de Docker, detén todos los contenedores de Docker primero, luego elige un contenedor que tenga la ingestión habilitada, establece la nueva etiqueta para la imagen basada en el lanzamiento publicado en Docker Hub - stellar/stellar-horizon, y reinicia el contenedor en el demonio de Docker, incluye la variable de entorno APPLY_MIGRATIONS=true en el entorno del contenedor, esto hará que Horizon ejecute automáticamente cualquier migración de base de datos que detecte que es necesaria.

  • Para instalaciones de Helm en Kubernetes, primero usa tu herramienta de CLI de Helm para detener todas las instancias de Horizon escalando todas tus instalaciones de Horizon (para ingestión y web) a 0 réplicas, las cuales creaste previamente en pasos de ejecución.

    helm upgrade all-my-horizon-installations \
    --namespace my-horizon-namespace-on-cluster \
    --set ingest.replicaCount=0 \
    --set web.replicaCount=0

    Ahora, usa Helm para iniciar solo una instancia de Horizon de una instalación de Helm que tiene la ingestión habilitada en el clúster de Kubernetes, establecerás la global.image.horizon.tag a la etiqueta de lanzamiento publicada en stellar/stellar-horizon

    helm upgrade my-horizon \
    --namespace my-horizon-namespace-on-cluster  \
    --set global.image.horizon.tag=new_horizon_release_number \
    --set ingest.horizonConfig.applyMigrations=True \
    --set ingest.replicaCount=1

Confirmando la actualización en la instancia de ingestión única primero​

Si tienes infraestructura de monitoreo en su lugar, entonces tienes dos opciones para evaluar el estado de la actualización:

  • Ver las salidas de métricas utilizando los paneles de grafana que aprovechan las consultas en el modelo de datos de métricas de Horizon para verificar estadísticas clave como la ingestión y los ledgers de red están avanzando y en paso.

  • Ver la ruta URL del 'estado' del servidor web de Horizon en la instancia actualizada:

    curl http://localhost:8000/

    La respuesta será el código de estado HTTP 200 y el cuerpo de la respuesta será una estructura de datos json basada en texto con información de diagnóstico sobre la versión actual del software de Horizon y los números de ledgers para la ingestión y la red, actualiza la URL cada 5 segundos aproximadamente, y deberías ver los números de ledgers de ingestión y red avanzando y en paso, indicando buena conexión a la red y la ingestión.

Si las métricas y/o la respuesta URL de 'estado' de Horizon no indican un estado saludable basado en la ingestión del ledger en avance, dos pasos para continuar con la evaluación:

  • Un retraso en que Horizon logre un estado saludable después de una actualización es esperado y legítimo para cualquier caso de actualización donde se mencionó State Rebuild o DB Migration en el delta de lanzamiento como parte del paso anterior Determinar la versión objetivo para la actualización. Típicamente las notas también mencionarán expectativas de marco de tiempo relativo para que estas se completen, lo cual puede ser considerado en cuánto tiempo esperar por el retraso.
  • Revisa los registros desde la instancia actualizada para confirmar qué está sucediendo. Cualquier State Rebuild o DB Migration iniciada será mencionada. Por ejemplo, una migración de base de datos será anotada en los registros con las siguientes líneas para inicio y finalización: 
    2023/09/22 18:27:01 Applying DB migrations...
    2023/09/22 18:27:01 successfully applied 5 Horizon migrations

Actualizar todas las instancias restantes​

En este punto, has actualizado una instancia de ingestión a la nueva versión de Horizon, ha actualizado automáticamente la base de datos si es necesario y la instancia está funcionando con un estado saludable. Ahora, instala la misma versión de software de Horizon en el resto de instancias, reiniciando cada una después de la actualización. Para instalaciones bare-metal y en demonios de Docker que seguramente será autoexplicativo sobre cómo lograr eso en el resto de instancias, en instalaciones de gráficos de Helm, ejecuta la actualización de helm nuevamente, configurando la etiqueta de imagen y también restaurando los valores originales de replicaCount:

helm upgrade all-my-horizon-installations \
--namespace my-horizon-namespace-on-cluster \
--set ingest.replicaCount=1 \
--set web.replicaCount=1 \
--set global.image.horizon.tag=new_horizon_release_number \
--set ingest.horizonConfig.applyMigrations=False

Para implementaciones en producción siguiendo el modelo de respaldo activo o azul/verde, esta es la oportunidad para confirmar que la implementación inactiva ha realizado correctamente la actualización y se encuentra estable, en este momento, cambia los balanceadores de carga ahora para redirigir el tráfico a la implementación inactiva, haciéndola la implementación activa. Ahora, puede llevar tiempo realizar la misma actualización en la otra implementación que ahora es inactiva.