Recuperación tras una actualización fallida de NGINX Plus: «versión X del módulo "M" en lugar de Y»

Liam CrillyDirector sénior de Gestión de Producto

Si utiliza módulos dinámicos, es posible que aparezca un error como este al actualizar a una nueva versión de NGINX o NGINX Plus:

Setting up nginx-plus (1.11.10-1~xenial) ...
nginx: [emerg] module "/etc/nginx/modules/ngx_http_geoip_module.so" version 1011005 instead of 1011006 in /etc/nginx/nginx.conf:7

nginx: configuration file /etc/nginx/nginx.conf test failed

invoke-rc.d: initscript nginx, action "upgrade" failed.

Lo más probable es que no haya actualizado el módulo dinámico especificado (archivo .so):

• Si utiliza NGINX Open Source, los módulos dinámicos deben compilarse para la versión a la que va a actualizar.
• Si utiliza NGINX Plus, los módulos dinámicos deben compilarse con la versión de NGINX Open Source correspondiente a la versión de NGINX Plus a la que va a actualizar.

En aras de la brevedad, a partir de ahora nos referiremos únicamente a NGINX Plus.

¡Que no cunda el 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 se realizan sin interrupciones, por lo que la versión anterior continúa ejecutándose cuando falla una actualización. Sin embargo, la actualización no se ha completado y el sistema se encuentra en un estado incoherente:

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

No reinicie manualmente nginx ni reinicie el sistema. Si lo hace, se producirá una interrupción del servicio, ya que los nuevos procesos de NGINX Plus no pueden iniciarse mientras haya módulos dinámicos que no estén sincronizados con la nueva versión de NGINX Plus.

Tenga en cuenta que el mensaje de error solo hace referencia al primer módulo incompatible encontrado durante el proceso de actualización, por lo que es importante localizar todas las directivas load_module de la configuración y asegurarse de que cada módulo esté compilado para la versión de NGINX correspondiente. Con cada versión de NGINX Plus se proporcionan las versiones correctas de todos los módulos dinámicos creados por NGINX y de terceros certificados, por lo que solo es necesario volver a compilar los módulos no certificados.En este artículo se explica cómo completar el proceso de actualización de forma segura.

¿Qué salió mal?

NGINX 1.11.5 y NGINX Plus R11 introdujeron la posibilidad de compilar módulos dinámicos para 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 los módulos dinámicos compilados para la versión correspondiente de NGINX Open Source falla debido a esta incompatibilidad de versiones.

Si un proveedor externo le suministró el módulo dinámico, deberá ponerse en contacto con él para obtener una nueva versión que se corresponda con la versión de NGINX de la versión de NGINX Plus a la que desea actualizar. Si el módulo dinámico se compiló a partir del código fuente (y tiene acceso a dicho código), siga leyendo.

El camino hacia la recuperación

Paso 0: Preparar el entorno de compilación

Recomendamos encarecidamente que compile los módulos dinámicos en un sistema independiente, al que aquí denominamos «entorno de compilación». De este modo, se reducen al mínimo el riesgo y la complejidad del sistema en el que ejecuta NGINX Plus con el módulo dinámico (al que denominamos «entorno de producción»). El entorno de compilación debe tener el mismo sistema operativo y la misma versión que el entorno de producción; además, deben estar instalados los siguientes componentes:

• Utilidad UnZip
• Compilador y utilidad make
• Biblioteca de expresiones regulares compatibles con Perl (archivos de desarrollo)
• Bibliotecas de compresión Zlib (archivos de desarrollo)

Para asegurarte de que tu entorno de compilación tenga instalados estos requisitos previos, ejecuta 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: Obtenga NGINX Open Source

1. En el entorno de producción, ejecute el siguiente comando para identificar la versión de NGINX Open Source que corresponde a la versión de NGINX Plus en ejecución. En esta salida aparece resaltada en naranja: NGINX 1.11.10, que corresponde a NGINX Plus R12.

production$ nginx -vnginx version: nginx/1.11.10 (nginx-plus-r12)

1. En el entorno de compilación, descargue el código fuente de la versión correspondiente de NGINX Open Source.

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

Paso 2: Obtenga el código fuente del módulo dinámico

Copie el código fuente del módulo dinámico en el directorio de compilación que prefiera. En este ejemplo, copiamos un módulo de muestra «Hola, mundo» de NGINX desde su repositorio de GitHub.

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

Paso 3: Compilar el módulo dinámico

1. Compile el módulo dinámico ejecutando primero el script configure de NGINX con el argumento --with-compat para que el módulo dinámico sea compatible a nivel binario con NGINX Plus. A continuación, ejecute make modules para compilar únicamente el módulo.

buildenv$ cd nginx-1.11.10/buildenv$ ./configure --with-compat --add-dynamic-module=../nginx-hello-world-module
buildenv$ make modules

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

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

1. Cree una copia del archivo del módulo que incluya la versión de NGINX Open Source en el nombre del archivo. Esto facilita la gestión de varias versiones del módulo dinámico en el entorno de producción.

buildenv$ cp objs/ngx_http_hello_world.so ./ngx_http_hello_world_1.11.10.so

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

Como creamos el módulo dinámico incluyendo la versión de NGINX Open Source en el nombre del archivo, podemos copiarlo de forma segura al entorno de producción sin afectar a su funcionamiento.

buildenv$ scp ./ngx_http_hello_world_1.11.10.so production:/etc/nginx/modules

Paso 5: Sustituir el módulo dinámico

En el entorno de producción, sustituya el archivo actual por el nuevo archivo .so. Es seguro hacerlo en este momento porque los módulos dinámicos solo se cargan en memoria cuando nginx se reinicia o se vuelve a cargar la configuración.

production$ cd /etc/nginx/modulesproduction$ cp ngx_http_hello_world.so ngx_http_hello_world_ROLLBACK.so
production$ ln -fs ngx_http_hello_world_1.11.10.so ngx_http_hello_world.so
production$ ls -gG
-rw-r--r-- 1 243576 Jan 31 16:18 ngx_http_hello_world_1.11.10.so
-rw-r--r-- 1 243576 Oct 20 10:40 ngx_http_hello_world_ROLLBACK.so
lrwxrwxrwx 1     24 Jan 31 16:26 ngx_http_hello_world.so -> ngx_http_hello_world_1.11.10.so

Paso 6: Complete la actualización de NGINX Plus

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

production$ nginx -tnginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

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

production$ service nginx upgradeStarting new master nginx:                                 [  OK  ]
Graceful shutdown of old nginx:                            [  OK  ]

Cómo evitar que falle la actualización

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

Sobre el autor

Liam CrillyDirector sénior de Gestión de Producto

Más artículos de Liam Crilly