Récupération après l’échec d’une mise à niveau de NGINX Plus : « version X du module “M” au lieu de Y »

Liam CrillyDirecteur senior de la gestion des produits

Si vous utilisez des modules dynamiques, il se peut qu’une erreur de ce type s’affiche lors de la mise à niveau vers une nouvelle version de NGINX ou 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.

La raison la plus probable est que vous n’avez pas mis à niveau le module dynamique spécifié (.so ):

• Si vous utilisez NGINX Open Source, les modules dynamiques doivent être compilés pour la version vers laquelle vous effectuez la mise à niveau.
• Si vous utilisez NGINX Plus, les modules dynamiques doivent être compilés avec la version de NGINX Open Source correspondant à la version de NGINX Plus vers laquelle vous effectuez la mise à niveau.

Par souci de concision, nous parlerons désormais uniquement de NGINX Plus.

Pas de panique !

Rassurez-vous, ce message d’erreur ne signifie pas que votre serveur NGINX Plus est hors service. Les mises à niveau de NGINX Plus s’effectuent sans interruption. Ainsi, en cas d’échec d’une mise à niveau, l’ancienne version continue de fonctionner. Toutefois, la mise à niveau est incomplète et votre système se trouve dans un état incohérent :

• Les processus NGINX Plus en mémoire exécutent l’ancienne version
• Tous les fichiers sur le disque relatifs à NGINX Plus correspondent à la nouvelle version
• Le module dynamique mentionné dans le message d’erreur a été compilé pour l’ancienne version

Ne redémarrez pas manuellement nginx et ne redémarrez pas le système. Cela entraînerait une interruption de service, car les nouveaux processus NGINX Plus ne peuvent pas démarrer tant que des modules dynamiques ne sont pas synchronisés avec la nouvelle version de NGINX Plus.

Notez que le message d’erreur concerne uniquement le premier module incompatible détecté au cours du processus de mise à niveau. Il est donc important de rechercher toutes les directives « load_module » dans votre configuration et de vérifier que chaque module est compilé pour la version appropriée de NGINX. Les versions adéquates de tous les modules dynamiques développés par NGINX et des modules dynamiques tiers certifiés sont fournies pour chaque version de NGINX Plus<. Vous devez donc recompiler uniquement les modules non certifiés.Cet article explique comment mener à bien le processus de mise à niveau en toute sécurité.

Qu’est-ce qui s’est mal passé ?

NGINX 1.11.5 et NGINX Plus R11 ont introduit la possibilité de compiler des modules dynamiques avec NGINX Open Source et de les charger dans NGINX Plus. Cette compatibilité binaire exige que le module et NGINX Plus reposent sur la même version open source de base. La mise à niveau de NGINX Plus sans avoir préalablement installé les modules dynamiques compilés avec la version correspondante de NGINX Open Source échoue en raison de cette incompatibilité de versions.

Si votre module dynamique a été fourni par un éditeur tiers, vous devez contacter celui-ci afin d’obtenir une nouvelle version correspondant à la version de NGINX utilisée par la version de NGINX Plus vers laquelle vous souhaitez effectuer la mise à niveau. Si votre module dynamique a été compilé à partir du code source (et que vous avez accès aux sources), poursuivez votre lecture.

La voie du rétablissement

Étape 0 : préparer l’environnement de compilation

Nous vous recommandons vivement de compiler les modules dynamiques sur un système distinct, que nous appelons ici l’« environnement de compilation ». Cette approche réduit les risques et la complexité du système sur lequel vous exécutez NGINX Plus avec le module dynamique (que nous appelons l’« environnement de production »). L’environnement de compilation doit utiliser le même système d’exploitation et la même version que l’environnement de production ; en outre, les composants suivants doivent être installés :

• Utilitaire UnZip
• Compilateur et utilitaire make
• Bibliothèque d’expressions régulières compatibles avec Perl (fichiers de développement)
• Bibliothèques de compression Zlib (fichiers de développement)

Pour vous assurer que ces prérequis sont installés dans votre environnement de compilation, exécutez la commande suivante.

• Pour Ubuntu/Debian :

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

• Pour CentOS/RHEL/Oracle Linux :

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

Étape 1 : Obtenir NGINX Open Source

1. Dans l’environnement de production, exécutez la commande suivante pour identifier la version de NGINX Open Source correspondant à la version de NGINX Plus en cours d’exécution. Elle est surlignée en orange dans cette sortie : NGINX 1.11.10, qui correspond à NGINX Plus R12.

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

1. Dans l’environnement de compilation, téléchargez les sources de la version appropriée de NGINX Open Source.

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

Étape 2 : obtenir les sources du module dynamique

Copiez le code source du module dynamique dans le répertoire de compilation de votre choix. Ici, nous copions un exemple de module NGINX « hello world » depuis son dépôt GitHub.

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

Étape 3 : compiler le module dynamique

1. Compilez le module dynamique en exécutant d’abord le script configure de NGINX avec l’argument --with-compat afin de rendre le module dynamique compatible au niveau binaire avec NGINX Plus. Exécutez ensuite make modules pour compiler uniquement le module.

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

1. Vérifiez que le processus de compilation a créé le module dynamique sous la forme d’un fichier « .so » dans le sous-répertoire « objs ».

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

1. Créez une copie du fichier du module en incluant la version de NGINX Open Source dans le nom du fichier. Cela simplifie la gestion de plusieurs versions du module dynamique dans l’environnement de production.

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

Étape 4 : copier le module dynamique dans l’environnement de production

Comme nous avons créé le module dynamique en incluant la version de NGINX Open Source dans le nom du fichier, nous pouvons le copier en toute sécurité dans l’environnement de production sans perturber son fonctionnement.

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

Étape 5 : remplacer le module dynamique

Dans l’environnement de production, remplacez le fichier .so actuel par le nouveau. Cette opération peut être effectuée sans risque à ce stade, car les modules dynamiques ne sont chargés en mémoire que lorsque nginx redémarre ou que la configuration est rechargée.

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

Étape 6 : terminer la mise à niveau de NGINX Plus

1. Exécutez la commande suivante pour vérifier que la version du module est correcte et que NGINX Plus est prêt à terminer le processus de mise à niveau.

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

1. Terminez le processus de mise à niveau afin que NGINX Plus utilise la nouvelle version et les modules dynamiques.

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

Prévenir l’échec de la mise à niveau

Lors de votre prochaine mise à niveau de NGINX Plus, vous pourrez gagner du temps et éviter les erreurs en suivant ces instructions avant la mise à niveau, afin que les modules dynamiques mis à jour soient déjà disponibles lorsque vous lancerez le processus de mise à niveau.

À propos de l’auteur

Liam CrillyDirecteur senior de la gestion des produits

Autres articles de Liam Crilly