失敗した NGINX Plus アップグレードからの回復: 「モジュール "M" バージョン X ではなく Y」

動的モジュールを使用している場合、新しい NGINX または NGINX Plus リリースへのアップグレード中に次のようなエラーが表示されることがあります。

nginx-plus (1.11.10-1~xenial) を設定しています... nginx: [emerg] モジュール "/etc/nginx/modules/ngx_http_geoip_module.so" バージョン 1011005 (/etc/nginx/nginx.conf:7 内の 1011006 ではなく) nginx: 設定ファイル /etc/nginx/nginx.conf のテストに失敗しました。invoke-rc.d: initscript nginx、アクション "upgrade" が失敗しました。

最も可能性の高い理由は、指定された動的モジュール ( .soファイル) をアップグレードしていないことです。

• NGINX オープンソースを実行している場合は、アップグレードするバージョンに合わせて動的モジュールをコンパイルする必要があります。
• NGINX Plus を実行している場合、動的モジュールは、アップグレード先の NGINX Plus リリースに対応する NGINX オープンソース バージョンに対してコンパイルする必要があります。

簡潔にするために、ここからは NGINX Plus のみを参照します。

慌てないで！

このエラー メッセージは、NGINX Plus サーバーがダウンしていることを示すものではありませんので、ご安心ください。 NGINX Plus のアップグレードはシームレスに行われるため、アップグレードが失敗しても古いバージョンが引き続き実行されます。 ただし、アップグレードは不完全であり、システムは不整合な状態にあります。

• メモリ内のNGINX Plusプロセスは古いバージョンを実行しています
• NGINX Plusに関連するディスク上のすべてのファイルは新しいバージョンに対応しています
• エラーメッセージに記載されている動的モジュールは古いバージョンに対してコンパイルされています

nginx を手動で再起動したり、システムを再起動したりしないでください。 これを実行すると、新しい NGINX Plus リリースと同期していない動的モジュールがある間は新しい NGINX Plus プロセスを開始できないため、ダウンタイムが発生します。

エラー メッセージは、アップグレード プロセス中に見つかった最初の互換性のないモジュールにのみ関連していることに注意してください。そのため、構成内のすべてのload_moduleディレクティブを見つけて、すべてのモジュールが適切な NGINX バージョンに対してコンパイルされていることを確認することが重要です。 NGINX Plus の各リリースには、NGINX が作成し認定したすべてのサードパーティ動的モジュールの正しいバージョンが提供されているため、認定されていないモジュールのみを再コンパイルする必要があります。この記事では、アップグレード プロセスを安全に完了する方法について説明します。

何が悪かったのでしょうか?

NGINX 1.11.5 およびNGINX Plus R11では、NGINX Open Source に対して動的モジュールをコンパイルし、NGINX Plus にロードする機能が導入されました。 このバイナリ互換性には、モジュールと NGINX Plus が同じ基本オープンソース バージョンを共有する必要があります。 対応する NGINX オープンソース バージョンに対して構築された動的モジュールを最初にインストールせずに NGINX Plus をアップグレードすると、このバージョンの不一致のために失敗します。

動的モジュールがサードパーティベンダーから提供された場合は、アップグレードする予定の NGINX Plus リリースの NGINX バージョンと一致する新しいバージョンについてベンダーに問い合わせる必要があります。 動的モジュールがソースからコンパイルされている場合 (そしてソースにアクセスできる場合) は、読み続けてください。

回復への道

ステップ0: ビルド環境を準備する

動的モジュールは、ここでは「ビルド環境」と呼ぶ別のシステムでコンパイルすることを強くお勧めします。 そうすることで、動的モジュールを使用して NGINX Plus を実行しているシステム (これを「本番環境」と呼びます) のリスクと複雑さが最小限に抑えられます。 ビルド環境には、運用環境と同じオペレーティング システムとバージョンが必要です。さらに、次のコンポーネントがインストールされている必要があります。

• 解凍ユーティリティ
• コンパイラとmakeユーティリティ
• Perl互換正規表現ライブラリ（開発ファイル）
• Zlib 圧縮ライブラリ (開発ファイル)

ビルド環境にこれらの前提条件がインストールされていることを確認するには、次のコマンドを実行します。

• Ubuntu/Debianの場合:

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

• CentOS/RHEL/Oracle Linuxの場合:

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

ステップ1: NGINXオープンソースを入手する

1. 実稼働環境で作業している場合は、次のコマンドを実行して、実行中の NGINX Plus リリースに対応する NGINX オープンソース バージョンを識別します。 この出力ではオレンジ色で強調表示されています。 NGINX 1.11.10 は、NGINX Plus R12 に相当します。

   運用$ nginx -v nginx バージョン: nginx/ 1.11.10 (nginx-plus-r12)

2. ビルド環境で作業し、適切な NGINX オープンソース バージョンのソースをダウンロードします。

   ビルド環境$ wget -qO - http://nginx.org/download/nginx-1.11.10 .tar.gz | tar zxfv -

ステップ2: 動的モジュールソースを取得する

動的モジュールのソース コードを任意のビルド ディレクトリにコピーします。 ここでは、GitHub リポジトリからサンプルの NGINX「hello world」モジュールをコピーします。

buildenv$ git clone https://github.com/perusio/nginx-hello-world-module.git 'nginx-hello-world-module' にクローンしています...

ステップ3: 動的モジュールをコンパイルする

1. まず、 --with-compat引数を指定して NGINX configureスクリプトを実行し、動的モジュールを NGINX Plus とバイナリ互換になるようにして、動的モジュールをコンパイルします。 次に、 make modulesを実行してモジュールだけをコンパイルします。

   buildenv$ cd nginx-1.11.10/ buildenv$ ./configure --with-compat --add-dynamic-module=../nginx-hello-world-module buildenv$モジュールを作成する

2. ビルド プロセスによって、動的モジュールがobjsサブディレクトリに.soファイルとして作成されたことを確認します。

   ビルドenv$ ls objs/*.so objs/ngx_http_hello_world.so

3. ファイル名に NGINX オープンソース バージョンを含むモジュール ファイルのコピーを作成します。 これにより、運用環境で動的モジュールの複数のバージョンを管理することが簡単になります。

   ビルドenv$ cp objs/ngx_http_hello_world.so ./ngx_http_hello_world_1.11.10.so

ステップ4: 動的モジュールを本番環境にコピーする

ファイル名に NGINX オープンソースのバージョンを付けて動的モジュールを作成したので、動作に影響を与えることなく本番環境に安全にコピーできます。

buildenv$ scp ./ngx_http_hello_world_1.11.10.so 本番環境:/etc/nginx/modules

ステップ5: ダイナミックモジュールのスワップ

実稼働環境で作業している場合は、新しい.soファイルを現在のファイルに置き換えます。 動的モジュールはnginx が再起動するか、設定が再ロードされたときにのみメモリにロードされるため、この時点でこれを行うのは安全です。

生産$ cd /etc/nginx/modules生産$ cp ngx_http_hello_world.so ngx_http_hello_world_ROLLBACK.so生産$ ln -fs ngx_http_hello_world_1.11.10.so ngx_http_hello_world.so生産$ ls -gG -rw-r--r-- 1 243576 1月31日 16:18 ngx_http_hello_world_1.11.10.so -rw-r--r-- 1 243576 10月20日 10:40 ngx_http_hello_world_ROLLBACK.so lrwxrwxrwx 1 24 1月31日 16:26 ngx_http_hello_world.so -> ngx_http_hello_world_1.11.10.so

ステップ6: NGINX Plusのアップグレードを完了する

1. 次のコマンドを実行して、モジュールのバージョンが正しいこと、および NGINX Plus がアップグレード プロセスを完了する準備ができていることをテストします。

   production$ nginx -t nginx: 設定ファイル /etc/nginx/nginx.conf の構文は正常です nginx: 設定ファイル /etc/nginx/nginx.conf のテストは成功しました

2. NGINX Plus が新しいリリースと動的モジュールを使用するように、アップグレード プロセスを完了します。

   production$ service nginx upgrade新しいマスター nginx を起動しています: [ OK ] 古い nginx を正常にシャットダウンしています: [ OK ]

アップグレードの失敗を防ぐ

次回 NGINX Plus をアップグレードするときは、アップグレード前にこれらの手順に従うことで時間を節約し、エラーを回避できます。これにより、アップグレード プロセスを開始するときに、更新された動的モジュールがすでに利用可能になります。