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

Si vous utilisez des modules dynamiques, vous risquez de voir une erreur comme celle-ci lors de la mise à niveau vers une nouvelle version de NGINX ou NGINX Plus :

Configuration de nginx-plus (1.11.10-1~xenial) ... nginx : [emerg] module "/etc/nginx/modules/ngx_http_geoip_module.so" version 1011005 au lieu de 1011006 dans /etc/nginx/nginx.conf:7 nginx : fichier de configuration /etc/nginx/nginx.conf test échoué invoke-rc.d : initscript nginx, action "upgrade" a échoué.

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

• Si vous exécutez NGINX Open Source, les modules dynamiques doivent être compilés avec la version vers laquelle vous effectuez la mise à niveau.
• Si vous exécutez NGINX Plus, les modules dynamiques doivent être compilés avec la version NGINX Open Source qui correspond à la version NGINX Plus vers laquelle vous effectuez la mise à niveau.

Par souci de concision, nous ferons désormais uniquement référence à NGINX Plus.

Ne pas paniquer!

Soyez assuré que ce message d’erreur n’indique pas que votre serveur NGINX Plus est en panne. Les mises à niveau de NGINX Plus sont transparentes, de sorte que l'ancienne version continue de fonctionner lorsqu'une mise à niveau échoue. Cependant, la mise à niveau est incomplète et votre système est 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 est compilé avec l'ancienne version

Ne redémarrez pas manuellement nginx ou ne redémarrez pas le système. Cela entraînera des temps d'arrêt car les nouveaux processus NGINX Plus ne pourront pas démarrer tant que des modules dynamiques ne seront pas synchronisés avec la nouvelle version de NGINX Plus.

Notez que le message d'erreur concerne uniquement le premier module incompatible détecté lors du processus de mise à niveau. Il est donc important de rechercher toutes les directives load_module dans votre configuration et de vous assurer que chaque module est compilé avec la version NGINX appropriée. Des versions correctes de tous les modules dynamiques tiers créés et certifiés par NGINX sont fournies pour chaque version de NGINX Plus. Vous devez donc recompiler uniquement les modules non certifiés. Cet article décrit comment effectuer 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 nécessite que le module et NGINX Plus partagent la même version open source de base. La mise à niveau de NGINX Plus sans installer au préalable les modules dynamiques créés avec la version NGINX Open Source correspondante échoue en raison de cette incompatibilité de version.

Si votre module dynamique a été fourni par un fournisseur tiers, vous devez contacter le fournisseur pour obtenir une nouvelle version, adaptée à la version NGINX de la version NGINX Plus vers laquelle vous souhaitez effectuer la mise à niveau. Si votre module dynamique a été compilé à partir des sources (et que vous avez accès aux sources), continuez à lire.

La voie vers la guérison

Étape 0 : Préparer l'environnement de construction

Nous vous recommandons fortement de compiler les modules dynamiques sur un système séparé, que nous appelons ici « environnement de build ». Cela minimise le risque et la complexité du système sur lequel vous exécutez NGINX Plus avec le module dynamique (nous appelons cela « l’environnement de production »). L'environnement de build doit avoir le même système d'exploitation et la même version que l'environnement de production ; de plus, les composants suivants doivent être installés :

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

Pour vous assurer que votre environnement de build dispose de ces prérequis installés, 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 : Obtenez NGINX Open Source

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

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

2. En travaillant dans l'environnement de construction, téléchargez les sources de la version NGINX Open Source appropriée.

   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 build de votre choix. Ici, nous copions un exemple de module NGINX « hello world » à partir de son référentiel GitHub.

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

Étape 3 : Compiler le module dynamique

1. Compilez le module dynamique en exécutant d’abord le script de configuration NGINX avec l’argument --with-compat pour rendre le module dynamique compatible 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$ créer des modules

2. Vérifiez que le processus de construction a créé le module dynamique en tant que fichier .so dans le sous-répertoire objs .

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

3. Créez une copie du fichier de module avec la version NGINX Open Source dans le nom de 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

Étant donné que nous avons créé le module dynamique avec la version NGINX Open Source dans le nom de fichier, nous pouvons le copier en toute sécurité dans l'environnement de production sans affecter le fonctionnement.

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

Étape 5 : Échanger le module dynamique

En travaillant dans l'environnement de production, remplacez le nouveau fichier .so par le fichier actuel. Cela peut être fait en toute sécurité à 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/modules production$ 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 31 janv. 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 janv. 31 16:26 ngx_http_hello_world.so -> ngx_http_hello_world_1.11.10.so

Étape 6 : Terminez 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 -t nginx : la syntaxe du fichier de configuration /etc/nginx/nginx.conf est correcte nginx : le test du fichier de configuration /etc/nginx/nginx.conf est réussi

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

   production$ service nginx upgrade Démarrage du nouveau maître nginx : [ OK ] Arrêt normal de l'ancien nginx : [ OK ]

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

La prochaine fois que vous mettrez à niveau 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 démarrez le processus de mise à niveau.