Recuperación de una actualización fallida de NGINX Plus: 'módulo "M" versión X en lugar de Y'

Si está utilizando módulos dinámicos, es posible que vea un error como este durante la actualización a una nueva versión de NGINX o NGINX Plus:

Configuración de nginx-plus (1.11.10-1~xenial) ... nginx: [emerg] módulo "/etc/nginx/modules/ngx_http_geoip_module.so" versión 1011005 en lugar de 1011006 en /etc/nginx/nginx.conf:7 nginx: la prueba del archivo de configuración /etc/nginx/nginx.conf falló. invoke-rc.d: script de inicio nginx, la acción "actualizar" falló.

La razón más probable es que no ha actualizado el módulo dinámico especificado (archivo .so ):

• Si está ejecutando NGINX Open Source, los módulos dinámicos deben compilarse con la versión a la que está actualizando.
• Si está ejecutando NGINX Plus, los módulos dinámicos deben compilarse con la versión de código abierto de NGINX que corresponde a la versión de NGINX Plus a la que está actualizando.

Por el bien de la brevedad de ahora en adelante nos referiremos únicamente a NGINX Plus.

¡No entrar en pánico!

Tenga la seguridad de que este mensaje de error no indica que su servidor NGINX Plus esté inactivo. Las actualizaciones de NGINX Plus son perfectas, por lo que la versión anterior continúa ejecutándose cuando falla una actualización. Sin embargo, la actualización está incompleta y su sistema se encuentra en un estado inconsistente:

• Los procesos NGINX Plus en la memoria están ejecutando la versión anterior
• Todos los archivos en disco relacionados con NGINX Plus corresponden a la nueva versión
• El módulo dinámico mencionado en el mensaje de error se compila con la versión anterior

No reinicie nginx manualmente ni reinicie el sistema. Si lo hace, se producirá un tiempo de inactividad porque los nuevos procesos de NGINX Plus no podrán iniciarse mientras haya módulos dinámicos desincronizados con la nueva versión de NGINX Plus.

Tenga en cuenta que el mensaje de error se relaciona solo con el primer módulo incompatible encontrado durante el proceso de actualización, por lo que es importante encontrar todas las directivas load_module en su configuración y asegurarse de que cada módulo esté compilado con la versión adecuada de NGINX. Se proporcionan versiones correctas de todos los módulos dinámicos de terceros creados y certificados por NGINX para cada versión de NGINX Plus, por lo que solo deberá recompilar los módulos no certificados. Este artículo describe cómo completar el proceso de actualización de forma segura.

¿Qué salió mal?

NGINX 1.11.5 y NGINX Plus R11 introdujeron la capacidad de compilar módulos dinámicos contra NGINX Open Source y cargarlos en NGINX Plus. Esta compatibilidad binaria requiere que el módulo y NGINX Plus compartan la misma versión base de código abierto. La actualización de NGINX Plus sin instalar primero módulos dinámicos creados con la versión de código abierto de NGINX correspondiente falla debido a esta falta de coincidencia de versiones.

Si su módulo dinámico fue suministrado por un proveedor externo, entonces deberá comunicarse con el proveedor para obtener una nueva versión, que coincida con la versión NGINX para la versión NGINX Plus a la que desea actualizar. Si su módulo dinámico se compiló desde la fuente (y tiene acceso a las fuentes), continúe leyendo.

El camino hacia la recuperación

Paso 0: Preparar el entorno de construcción

Le recomendamos encarecidamente que compile módulos dinámicos en un sistema separado, al que aquí llamamos el “entorno de compilación”. Al hacerlo se minimiza el riesgo y la complejidad del sistema donde se ejecuta NGINX Plus con el módulo dinámico (lo llamamos el “entorno de producción”). El entorno de compilación debe tener el mismo sistema operativo y versión que el entorno de producción ; además, deben estar instalados los siguientes componentes:

• Utilidad de descompresión
• Compilador y utilidad de creación
• Biblioteca de expresiones regulares compatible con Perl (archivos de desarrollo)
• Bibliotecas de compresión Zlib (archivos de desarrollo)

Para garantizar que su entorno de compilación tenga estos requisitos previos instalados, ejecute el siguiente comando.

• Para Ubuntu/Debian:

  buildenv$ sudo apt-get install unzip gcc make libpcre3-dev zlib1g-dev

• Para CentOS/RHEL/Oracle Linux:

  buildenv$ sudo yum install unzip gcc make pcre-devel zlib-devel

Paso 1: Obtener NGINX de código abierto

1. Trabajando en el entorno de producción, ejecute el siguiente comando para identificar la versión de código abierto de NGINX que corresponde a la versión de NGINX Plus en ejecución. Está resaltado en naranja en esta salida: NGINX 1.11.10, que corresponde a NGINX Plus R12.

   producción$ nginx -v versión de nginx: nginx/ 1.11.10 (nginx-plus-r12)

2. Mientras trabaja en el entorno de compilación, descargue las fuentes para la versión de código abierto NGINX adecuada.

   build-env$ wget -qO - http://nginx.org/download/nginx-1.11.10 .tar.gz | tar zxfv -

Paso 2: Obtener las fuentes del módulo dinámico

Copie el código fuente del módulo dinámico en el directorio de compilación que elija. Aquí copiamos un módulo NGINX “hello world” de muestra de su repositorio de GitHub.

buildenv$ git clone https://github.com/perusio/nginx-hello-world-module.git Clonando en 'nginx-hello-world-module'...

Paso 3: Compilar el módulo dinámico

1. Compile el módulo dinámico ejecutando primero el script de configuración de NGINX con el argumento --with-compat para hacer que el módulo dinámico sea compatible binariamente con NGINX Plus. Luego, ejecute make modules para compilar solo el módulo.

   buildenv$ cd nginx-1.11.10/ buildenv$ ./configure --with-compat --add-dynamic-module=../nginx-hello-world-module buildenv$ crear módulos

2. Verifique que el proceso de compilación haya creado el módulo dinámico como un archivo .so en el subdirectorio objs .

   buildenv$ ls objs/*.so objs/ngx_http_hello_world.so

3. Cree una copia del archivo del módulo con la versión de código abierto NGINX en el nombre del archivo. Esto hace que sea más sencilla la gestión de múltiples versiones del módulo dinámico en el entorno de producción.

   buildenv$ cp objs/ngx_http_hola_mundo.so ./ngx_http_hola_mundo_1.11.10.so

Paso 4: Copiar el módulo dinámico al entorno de producción

Debido a que creamos el módulo dinámico con la versión de código abierto NGINX en el nombre de archivo, podemos copiarlo de forma segura al entorno de producción sin afectar el funcionamiento.

buildenv$ scp ./ngx_http_hello_world_1.11.10.so producción:/etc/nginx/modules

Paso 5: Intercambiar el módulo dinámico

Al trabajar en el entorno de producción, intercambie el nuevo archivo .so para reemplazar el actual. Es seguro hacerlo en este punto porque los módulos dinámicos se cargan en la memoria solo cuando nginx se reinicia o se vuelve a cargar la configuración.

producción$ cd /etc/nginx/modules producción$ cp ngx_http_hello_world.so ngx_http_hello_world_ROLLBACK.so producción$ ln -fs ngx_http_hello_world_1.11.10.so ngx_http_hello_world.so producción$ ls -gG -rw-r--r-- 1 243576 31 ene. 16:18 ngx_http_hello_world_1.11.10.so -rw-r--r-- 1 243576 20 oct. 10:40 ngx_http_hello_world_ROLLBACK.so lrwxrwxrwx 1 24 31 ene. 16:26 ngx_http_hello_world.so -> ngx_http_hola_mundo_1.11.10.so

Paso 6: Complete la actualización de NGINX Plus

1. Ejecute el siguiente comando para probar que la versión del módulo sea correcta y que NGINX Plus esté listo para completar el proceso de actualización.

   producción$ nginx -t nginx: la sintaxis del archivo de configuración /etc/nginx/nginx.conf es correcta nginx: la prueba del archivo de configuración /etc/nginx/nginx.conf es exitosa

2. Complete el proceso de actualización para que NGINX Plus utilice la nueva versión y los módulos dinámicos.

   producción$ servicio nginx actualización Iniciando nuevo maestro nginx: [ OK ] Apagado correcto del antiguo nginx: [ OK ]

Cómo prevenir el fallo de la actualización

La próxima vez que actualice NGINX Plus, podrá ahorrar tiempo y evitar errores siguiendo estas instrucciones antes de la actualización para que los módulos dinámicos actualizados ya estén disponibles cuando inicie el proceso de actualización.