NGINX から OpenResty への移行は、既存の設定をそのまま移し、新旧インスタンスを並行稼働させて同じリクエストの結果を比較し、問題がなければ段階的にトラフィックを切り替えるのが安全です。OpenResty は標準 NGINX の設定構文と互換ですが、組み込まれているモジュール、デフォルトパス、実行環境が異なることが多いため、本番の NGINX をそのまま OpenResty に差し替えるとリスクが伴います。

移行前に両者の位置付けを確認するには、OpenResty と NGINX の比較:ゲートウェイがビジネスロジックを担うときをご覧ください。

移行の基本方針:まず揃え、その後に拡張

OpenResty は NGINX コアを基盤としているため、ほとんどの NGINX 標準ディレクティブをそのまま使えます。ただし、構文互換性があるからといって、設定ファイルをコピーするだけで必ず動くわけではありません。ビルドオプション、モジュール一覧、デフォルトのインストールパスが異なることが多く、そのまま置き換えると互換性の問題が起きやすくなります。

最も安全なのは、ゲートウェイ基盤の置き換えと新機能の追加を分けて進めることです。まず現在の設定を変更せずに移行し、NGINX と OpenResty を並行稼働させ、同じリクエストへのプロキシ動作が一致することを確認します。安定した後で、Lua による API 認証などの新しいビジネスロジックを段階的に導入します。こうしておけば、問題が発生した場合に、原因が基本環境と新しい Lua コードのどちらにあるかを切り分けやすくなります。

具体的な作業は次の 4 ステップで進めます。まだ環境がない場合は、OpenResty のインストールを参照してください。

既存 NGINX のビルドと設定の棚卸し

移行を始める前に、本番環境を調査してバックアップします。

  1. バージョンとビルドオプションを確認: 本番で実際に動作している NGINX バイナリを特定して nginx -V を実行し、バージョンと configure arguments をすべて記録します。
  2. 設定全体を出力: nginx -T を実行します。本番起動時に -p、-c、-g などの引数があれば、同じ引数を指定してください。-T は構文を検査するだけでなく、メイン設定と include で読み込まれるすべてのファイルを出力するため、依存関係の把握に役立ちます。
  3. バックアップと記録: 設定ファイルとディレクトリ構成を完全にバックアップし、サービスの実行ユーザーと起動コマンドを記録します。

モジュール・ディレクティブ・ファイルパスの確認

棚卸し後、互換性の問題が起きやすい箇所を重点的に確認します。

  • 組み込みモジュールとコアバージョンの違い: nginx -V と openresty -V の出力を比較します。設定テストで unknown directive が出た場合は、元の NGINX で http_sub_module など、デフォルトでは有効にならないモジュールを追加で有効にしていたかどうかを確認します。NGINX コアのバージョン差にも注意してください。新しい NGINX Mainline のディレクティブを使用しているなら、移行先 OpenResty のコアにその機能が含まれているかを確認します。
  • サードパーティ C モジュール(エラーが多発する箇所): 圧縮用の ngx_brotli、可観測性のための OpenTelemetry モジュール、以前に C で独自開発した社内モジュールなど、設定内のすべての load_module を調べます。元の NGINX 向けにビルドした .so ファイルは OpenResty にそのまま使えません。 両方で NGINX の --with-compat を有効にしていても、起動時に NGINX のバージョンとビルド署名が厳密に検査されます。バージョンが一致しなければ module "…" version … instead of …、ビルド署名に互換性がなければ module "…" is not binary compatible というエラーになり、いずれの場合も起動しません。動的 C モジュールは移行先 OpenResty 用に再ビルドしてください。元の NGINX に静的にコンパイルされていた自社開発モジュールについては、この機会に、OpenResty の Lua エコシステムで置き換えられるかを検討するのもよいでしょう。
  • パスと権限: include、TLS 証明書、ログ、PID、一時ディレクトリを確認します。絶対パスは通常問題ありませんが、相対パスは起動時の -p(prefix)を基準に解決されます。OpenResty に切り替えるとデフォルトの作業ディレクトリが変わるため、相対パスでファイルを見つけられなくなることがあります。新しいインスタンスの実行ユーザー(nobody や nginx など)に必要な読み書き権限があるかも確認してください。

2 つのインスタンスの並行稼働と同一リクエストでの比較

-t の構文検査に通っても、起動できることがわかるだけで、プロキシ動作が同じであることまでは保証されません。テスト環境で -p により別々の作業ディレクトリを指定し、NGINX と OpenResty を異なるポートで並行稼働させ、同じリクエストへのレスポンスを比較するのが安全です。

以下のローカル環境での最小構成の検証では、nginx、openresty、python3 がインストール済みとします。NGINX は 18080、OpenResty は 18082 で待ち受け、両方とも 18081 で待ち受けるアップストリームサービスへ /api/ を転送します。

一時ディレクトリを作成し、Python でモックのアップストリームサーバーを起動します。

check_dir=$(mktemp -d)
mkdir -p "$check_dir/conf" "$check_dir/logs" "$check_dir/upstream/api"
printf 'upstream ok\n' > "$check_dir/upstream/api/ping"
python3 -m http.server 18081 --bind 127.0.0.1 --directory "$check_dir/upstream" &
upstream_pid=$!

curl -fsS http://127.0.0.1:18081/api/ping を実行し、upstream ok が返ることを確認します。

検証する設定を $check_dir/conf/nginx.conf に保存します。一般的な転送ヘッダーの設定も加え、あわせて検証できるようにしています。

pid logs/nginx.pid;
error_log logs/error.log;

events {}

http {
    access_log logs/access.log;

    server {
        listen 127.0.0.1:18082;
        server_name gateway.test;

        location /api/ {
            proxy_set_header Host $host;
            proxy_set_header X-Forwarded-Proto $scheme;
            proxy_pass http://127.0.0.1:18081;
        }
    }
}

同じ設定を NGINX 用にもコピーし、待ち受けポートだけを 18080 に変えます。それぞれに -p で別の作業ディレクトリを指定し、設定を検査してから起動します。

baseline_dir=$(mktemp -d)
mkdir -p "$baseline_dir/conf" "$baseline_dir/logs"
sed 's/127\.0\.0\.1:18082/127.0.0.1:18080/' "$check_dir/conf/nginx.conf" \
    > "$baseline_dir/conf/nginx.conf"

nginx -p "$baseline_dir/" -c conf/nginx.conf -t &&
    nginx -p "$baseline_dir/" -c conf/nginx.conf
openresty -p "$check_dir/" -c conf/nginx.conf -t &&
    openresty -p "$check_dir/" -c conf/nginx.conf

両方のポートに同じリクエストを送り、プロキシ結果を比較します。Bash/Zsh では diff -u <(curl ...) <(curl ...) でも出力を比較できます。

curl -isS -H 'Host: gateway.test' http://127.0.0.1:18080/api/ping
curl -isS -H 'Host: gateway.test' http://127.0.0.1:18082/api/ping

通常、両方とも 200 と upstream ok を返します。/api/missing のような存在しないパスでは、どちらも 404 になります。Server や Date などのレスポンスヘッダーに違いがあっても問題ありません。クライアントが依存するステータスコード、レスポンスボディ、アプリケーション固有のレスポンスヘッダーを重点的に比較してください。

実際の移行では、本番設定を複製し、正常系と想定される異常系を含む主要ルートの代表リクエストを再生します。両者のエラーログ、アップストリームが受信したリクエストヘッダー、アクセスログ、TLS ハンドシェイクが一致しているかも確認します。

ローカルでの検証が終わったら、一時インスタンスとテスト用アップストリームを停止します。

openresty -p "$check_dir/" -c conf/nginx.conf -s quit
nginx -p "$baseline_dir/" -c conf/nginx.conf -s quit
kill "$upstream_pid"

段階的なトラフィック切り替えとロールバックの準備

テスト環境で問題がないことを確認できたら、本番切り替えを準備します。

ゲートウェイの前段にロードバランサーがある場合は、既存 NGINX を稼働させたまま、まず少量のトラフィックを OpenResty に流すカナリアリリースを開始します。切り替え前に、観察期間と、トラフィックを増やす条件やロールバックを開始する指標のしきい値(特にエラー率とレイテンシ)を決めます。カナリアリリース中は新旧インスタンスの監視指標とアップストリームサービスの状態を注視し、基準を満たしたら徐々にトラフィックの割合を増やします。しきい値を超えた場合はすぐに元の NGINX に戻し、重要なリクエストを再送して復旧を確認します。

ロールバック時に見落としやすい点が 2 つあります。

  1. セキュリティポリシーの整合: OpenResty への移行と同時に、不正なリクエストを遮断するなど新しい認証・セキュリティロジックを導入する場合、元の NGINX にも最低限の遮断ポリシーが用意されていることを必ず確認してください。そうでないとロールバック時に防御が失われるおそれがあります。
  2. ポート競合への対処: ロードバランサーがなく、同じマシン上で 80/443 番ポートを新旧サービスが交互に使う場合、段階的な切り替え(カナリアリリース)はできません。「OpenResty を停止 → 元の NGINX を起動 → テストリクエストを送信して確認」という一括ロールバック用スクリプトを必ず事前に用意し、障害時に数秒で復旧できるようにします。

よくある質問

NGINX の nginx.conf は OpenResty でそのまま使えますか?

ほとんどの NGINX 標準ディレクティブはそのまま使えます。ただし、構文互換だからといって設定ファイルをコピーするだけで動くとは限りません。元の NGINX で追加有効化していたモジュール、NGINX コアのバージョン差、相対パスの基準になる -p(prefix)の違いを確認し、-t で検査したうえで、並行稼働して同じリクエストの結果を比較してください。

NGINX 用にビルドした動的モジュールは OpenResty で使えますか?

使えません。両方で --with-compat を有効にしていても、起動時に NGINX のバージョンとビルド署名が検査され、一致しなければ module "…" version … instead of … や module "…" is not binary compatible というエラーで起動しません。動的 C モジュールは移行先の OpenResty 用に再ビルドしてください。

移行中に問題が起きたらどう戻しますか?

切り替え前に、エラー率とレイテンシのしきい値を決めておき、超えたらすぐに元の NGINX に戻して重要なリクエストを再送し、復旧を確認します。ロードバランサーがなく同じマシンで 80/443 番ポートを使い回す場合は、「OpenResty を停止 → 元の NGINX を起動 → テストリクエストで確認」を一括で行うスクリプトを事前に用意しておきます。

まとめと次のステップ

NGINX から OpenResty への移行で大切なのは、一度にすべてを置き換えるのではなく、リスクを分割することです。既存設定をそのまま移し、プロキシ動作の一致を確認してから、Lua のビジネスロジックを段階的に追加します。

作業は 4 ステップで進めます。まず nginx -V と nginx -T で既存のビルドと設定を把握します。次に、モジュール、コアバージョン、動的モジュール、ファイルパスを確認します。続いてテスト環境で新旧インスタンスを並行稼働させ、同じリクエストのステータスコード、レスポンスボディ、アプリケーション固有のレスポンスヘッダーを比較します。最後に、ロールバックのしきい値と手順を決めて段階的に切り替えます。本番切り替え後に問題が発生しても、基本設定と追加した Lua コードのどちらに原因があるか素早く判断し、必要なら元の NGINX に戻せます。

本記事はOpenResty チュートリアルシリーズの一部です。移行後はOpenResty の構成要素で、既存のプロキシ設定の上でゲートウェイを拡張できるモジュールや Lua ライブラリをご確認ください。

このチュートリアルが気に入っていただけましたら、ぜひ本ブログサイトおよび弊社の YouTube チャンネルをご購読ください。ありがとうございます!

著者について

章亦春(GitHub ハンドル: agentzh)は、OpenResty® オープンソースプロジェクトのオリジナル作成者であり、OpenResty Inc. の CEO です。

章亦春は「オープンソース技術」の最も初期の提唱者およびリーダーの一人です。Cloudflare や Yahoo! など、国際的に著名な複数のテック企業で勤務しました。「エッジコンピューティング」「動的トレーシング」「マシンコーディング」の先駆者であり、22 年以上のプログラミング経験と 16 年のオープンソース経験を持ちます。章亦春はオープンソース界で OpenResty® のプロジェクトリーダーとして広く知られており、同プロジェクトは全世界で 4,000 万以上のWeb サイトドメインに採用されています。

OpenResty Inc. は章亦春が 2017 年に設立したエンタープライズソフトウェアスタートアップで、世界最大級の企業を顧客に持ちます。フラッグシップ製品の OpenResty XRay は、動的トレーシング技術を大幅に強化・活用する非侵入型のプロファイリングおよびトラブルシューティングツールです。また、OpenResty Edge 製品は、強力な分散トラフィック管理およびプライベート CDN ソフトウェア製品です。

熱心なオープンソースコントリビューターとして、章亦春は Linux カーネル、Nginx、LuaJIT、GDB、SystemTap、LLVM、Perl など、数多くのオープンソースプロジェクトに 100 万行以上のコードを貢献しています。また、60 以上のオープンソースソフトウェアライブラリを開発しています。

翻訳

英語版の原文と日本語訳版(本文)をご用意しております。読者の皆様による他の言語への翻訳版も歓迎いたします。全文翻訳で省略がなければ、採用を検討させていただきます。心より感謝申し上げます!