Kong Enterprise LTS 2.8 から 3.4 へのアップグレードガイド

Kong Gatewayは、 Kong Gateway Enterpriseの長期サポート（LTS）バージョン間の直接アップグレードをサポートします。

このガイドでは、Kong Gateway Enterprise 2.8 LTSからKong Gateway Enterprise 3.4 LTSへのアップグレードについて、特に2.8.0.0-2.8.4.1から3.4.0.0までをカバーして説明します。各エントリを慎重に確認し、それに応じて構成を変更します。

LTSのアップグレードには3つのアップグレードストラテジがあります。このガイドでは、 Kong Gatewayがサポートする各デプロイメントモードに最適な戦略を指定します。さらに、アップグレードプロセスで重要な役割を果たすいくつかの基本的な要素をリストアップし、データのバックアップと復元の方法について説明します。

このガイドでは、Kong Gatewayのコンテキスト内で次の用語を使用します。

アップグレード ：Kong Gatewayの古いバージョンから新しいバージョンに切り替える全体的なプロセスです。
移行 : データストアのデータを新しい環境に移行します。たとえば、2.8のデータを古いPostgreSQLインスタンスから3.4の新しいインスタンスに移動するプロセスは、データベース移行と呼ばれます。

アップグレードを確実に成功させるには、このガイドのすべての手順をよくお読みください。すべての準備手順を理解することと、デプロイメントタイプに基づき推奨アップグレードパスを選択することが非常に重要です。

注意 : このドキュメントで説明されている移行パターンは、Kong Gateway Enterprise 2.8 LTSとKong Gateway Enterprise 3.4 LTS間の2つのLTSバージョンでのみ発生します。このドキュメントを他のリリース間隔に適用すると、データベースの変更が誤った順序で実行され、データベーススキーマが壊れた状態になる可能性があります。他のバージョン間で移行するには、一般的なアップグレードガイドを参照してください。

前提条件

3.4以降では、Cassandraはサポートされていません。 Cassandraをデータストアとして使用している場合は、まずCassandraの移行を行い、その後、アップグレードを行います。
プラットフォームのバージョンとアップグレード先ののバージョン間のバージョン互換性を確認します。
KICアップグレードの互換性を確認します。
decKを使用している場合は、最新バージョンにアップグレードします。

このドキュメントにはアップグレードに必要なすべての操作知識が記載されているため、このドキュメントをよくお読みになり、アップグレードプロセスを正常に完了してください。

アップグレード手順の概要

準備フェーズ

Kong Gateway 3.4LTS にアップグレードする前に、いくつかの手順を完了させる必要があります。

リストされている前提条件をすべて実行します。
データベースまたは宣言型構成ファイルをバックアップします。
お客様のデプロイメントトポロジーに基づいて、適切なアップグレードストラテジを選択します。
デプロイメントに影響する下位互換性のない変更がないか、2.8から3.4へのKong Gatewayの変更を確認してください。
LTSリリース間でkong.confファイルに加えられた変更を徹底的に調べます。
選択したストラテジを使用して、運用前環境で移行をテストします。

アップグレードの実行

実際の以降の実行は、Kong Gatewayでのデプロイメントのタイプによって異なります。アップグレードプロセスのこの部分では、準備フェーズで決定したストラテジを使用します。

選択したアップグレードストラテジをdev上で実行します。
devからprodに移行します。
スモークテスト。
アップグレードを終了するか、ロールバックして再試行します。

それでは、バックアップオプションから始めて準備に移りましょう。

準備：バックアップストラテジを選択する

アップグレード中およびデータベース移行中に kong migrations コマンドを使用すると元に戻せません。アップグレードする前に、必ずデータベースまたは宣言型構成ファイルをバックアップしてください。

Kong Gatewayエンティティのバックアップには主に2つの種類があります。

データベースのバックアップ : PostgreSQLは、信頼性と性能に優れ、データのバックアップや復元時の一貫性を保証する、ネイティブなエクスポートとインポートのツールを備えています。Kong Gatewayを従来モードまたはハイブリッドモードで実行している場合は、常にデータベースネイティブのバックアップを実行する必要があります。
宣言型バックアップ ：Kongには、宣言形式でのKong Gatewayエンティティの管理をサポートするdecKとKong CLIという 2 つの宣言型バックアップツールが付属しています。従来型およびハイブリッドモードのデプロイメントでは、これらのツールを使用して二次バックアップを作成してください。DBレスモードのデプロイメントの場合は、Kong CLIを使用して、宣言型構成ファイルを手動で管理します。

回復の柔軟性を高めるため、可能であれば、両方の方法を使用してデータをバックアップすることを強くお勧めします。

データベースネイティブツールは、宣言型ツールに比べて堅牢でかつデータを即座に復元できます。データが破損した場合は、まずデータベースレベルの復元を実行してみてください。あるいは、新しいデータベースをブートストラップし、宣言型ツールを使用してバックアップファイルから設定を復元してください。

バックアップと復元のガイドを確認して、構成のバックアップを準備します。問題が発生してロールバックする必要がある場合は、そのガイドを参照して古いデータストアを復元することもできます。

準備：デプロイメントモードに基づいてアップグレードストラテジを選択する

このセクションで紹介するアップグレードストラテジは一般的なものであり、実際のデプロイメント環境によっては適合しない場合があります。

以下のデプロイメントモードを選択します。

従来モード
DBレスモード
ハイブリッドモード

意思決定プロセスがどのように機能するかを詳しく説明したフローチャートを以下に示します。

 
flowchart TD
    A{Deployment type?} --> B(Traditional mode)
    A{Deployment type?} --> C(Hybrid mode)
    A{Deployment type?} --> D(DB-less mode)
    A{Deployment type?} --> E(Konnect DP)
    B ---> F{Enough hardware to 
    run another cluster?}
    C --> G(Upgrade CP first) & H(Upgrade DP second)
    D ----> K([Rolling upgrade])
    E ----> K
    G --> F
    F ---Yes--->I([Dual-cluster upgrade])
    F ---No--->J([In-place upgrade])
    H ---> K
    click K "/gateway/latest/upgrade/rolling-upgrade/"
    click I "/gateway/latest/upgrade/dual-cluster/"
    click J "/gateway/latest/upgrade/in-place/"

図1：デプロイメントタイプに基づいてアップグレードストラテジを選択します。従来のモードでは、十分なリソースがある場合はデュアルクラスタアップグレードを、十分なリソースがない場合はインプレースアップグレードを選択してください。DBレスモードおよびKonnectDPの場合は、ローリングアップグレードを使用します。ハイブリッドモードの場合、CPには従来のモードストラテジの1つを使用し、DPにはローリングアップグレードを使用します。

各ストラテジの詳細については、次のセクションを参照してください。

従来モード

従来モードのデプロイメントとは、すべてのKong Gatewayコンポーネントが1つの環境で実行され、コントロールプレーン（CP）とデータプレーン（DP）の分離がない場合です。

従来モードでKong Gatewayをアップグレードする場合、次の2つのオプションがあります。

デュアルクラスタアップグレード: バージョン Y の新しい Kong Gateway クラスタが現在のバージョン X とともにデプロイされるため、アップグレードプロセス中は 2 つのクラスタが同時にリクエストを処理します。
インプレースアップグレード：インプレースアップグレードは既存のデータベースを再使用します。最初にクラスタXを終了してから、新しいクラスタYがデータベースを指すように構成する必要があります。

別のクラスターを同時に実行するリソースがある場合は、デュアルクラスターアップグレードを使用することをお勧めします。インプレース方式は、ビジネスダウンタイムを引き起こすため、リソースが限られている場合にのみ使用してください。

デュアルクラスターのアップグレード

デュアルクラスタのアップグレードストラテジを使用すると、ダウンタイムなしでKong GatewayをあるLTSバージョンから別のLTSバージョンにアップグレードできます。このアプローチでは、アップグレードされたバージョンのKong Gatewayを実行する新しいクラスタを、現在のバージョンを実行している既存のクラスタと一緒にセットアップします。

高いレベルで、一般的にこのプロセスには以下の手順が含まれます。

同じ規模のデプロイメントのプロビジョニング ：アップグレードされた Kong Gateway を実行する新しいクラスタの容量とリソースが、既存のクラスタと同じであるか確認する必要があります。これにより、両方のクラスタが同じ量のトラフィックとワークロードを処理できるようになります。
デュアルクラスタデプロイメントの設定 ：新しいクラスタがプロビジョニングされたら、APIと構成を両方のクラスタに同時に展開できます。デュアルクラスタデプロイメントでは、古いクラスタと新しいクラスタの両方を共存させ、リクエストを並行して処理できます。
データ同期 ：デュアルクラスタ展開では、両方のクラスタに同じデータがあることを確認するため、データ同期が不可欠です。これには、古いクラスタから新しいクラスタへのデータの移行や、両方のクラスタの同期を維持するための共有データストレージソリューションの設定が含まれます。スナップショットまたは pg_restore を使用して、古いクラスタから新しいクラスタにデータベースをインポートします。
トラフィックの再ルーティング ：新しいクラスタは古いクラスタと並行して実行されているので、受信トラフィックを徐々に新しいクラスタにルーティングし始めることができます。このプロセスは、ユーザーへの影響を最小限に抑えるため、段階的に実行することも、制御された切り替えメカニズムを通じて実行することもできます。これは、DNS、Nginx、F5、またはCanaryプラグインが有効になっている Kong Gateway ノードなど、どのロードバランサーでも実現できます。
テストと検証 ：新しいクラスタへの完全な切り替えを行う前に、アップグレードされたバージョンの機能を徹底的にテストして検証することが不可欠です。これには、API、プラグイン、認証メカニズム、その他の機能性が期待通りに動作することを確認するためのテストが含まれます。
完全な切り替え ：アップグレードしたクラスタが完全に機能し安定していることが確認できたら、すべての受信トラフィックを新しいクラスタにリダイレクトできます。この手順により、アップグレードプロセスが完了し、古いクラスタが廃止されます。

このデュアルクラスタのデプロイストラテジに従うことで、Kong GatewayをあるLTSバージョンから別のLTSバージョンに、スムーズでダウンタイムなしにアップグレードできます。このアプローチにより、アップグレードプロセス全体を通じて、ユーザーに対する高可用性と中断のないサービスが保証されます。

インプレースアップグレード

インプレースアップグレードでは、同じインフラ上でアップグレードを実行できますが、実際のアップグレードプロセスでは、ある程度のダウンタイムが必要です。アップグレードを実行できる、適切なメンテナンスまたはダウンタイムウィンドウを計画します。この間、Kong Gatewayは一時的に利用できなくなります。

ダウンタイムなしで行う必要があるシナリオでは、デュアルクラスタアップグレードを検討し、追加のリソースと複雑さに注意してください。

DB-lessモード

DBレスモードでは、独立した各Kong Gatewayノードは、永続的なデータベースストレージを使用せずに宣言型Kong Gateway構成データのコピーをメモリにロードするため、一部のノードの障害が他のノードに広がることはありません。

このモードでのデプロイメントでは、ローリングアップグレードストラテジを使用する必要があります。 deck gateway validate または kong config parse コマンドを使用して、バージョン Y の宣言型 YAML コンテンツの有効性を解析できます。

アップグレードを開始する前に、現在のkong.yamlファイルをバックアップする必要があります。

ハイブリッドモード

ハイブリッドモードは、1 つ以上のコントロールプレーン (CP) ノードと 1 つ以上のデータプレーン (DP) ノードで構成されます。 CP ノードはデータベースを使用して Kong 構成データを保存しますが、DP ノードは必要な情報をすべて CP から取得するため、データベースを使用しません。推奨されるアップグレードプロセスは、ノード (CP または DP) の種類ごとに異なるアップグレードストラテジを組み合わせたものです。

ハイブリッドモードアップグレードにおける主な課題は、CP と DP 間の通信です。ハイブリッドモードでは CP のマイナーバージョンが DP のマイナーバージョン以上である必要があるため、DP ノードの前に CP ノードをアップグレードする必要があります。アップグレードは2段階に分けて実施する必要があります。

まず、DPノードがAPIリクエストを処理している間に、従来モードセクションの推奨事項に従ってCPをアップグレードします。
次に、DBレスモードセクションの推奨事項を使用して、DPノードをアップグレードします。バージョンの競合を回避するために、新しいDPノードを新しいCPにポイントします。

CP と DP 間のロールのデカップリング機能によって、CP をアップグレードしながら DP ノードが API リクエストを処理できるようになります。この方法により、ビジネスのダウンタイムが発生しません。

カスタムプラグイン（独自のプラグインまたは Kong Gateway に付属していないサードパーティ製プラグイン）は、ハイブリッドモードでコントロールプレーン（CP）とデータプレーン（DP）の両方にインストールする必要があります。プラグインは、最初にコントロールプレーン（CP）にインストールし、次にデータプレーン（DP）にインストールします。

ハイブリッドモードデプロイメントのオプション詳細については、次のセクションを参照してください。

コントロールプレーン（CP）

CPノードはDPノードよりも先にアップグレードする必要があります。CPノードは管理者専用ロールを提供し、データベースのサポートが必要です。そのため、図2と図3で説明するように、従来のモード（デュアルクラスタまたはインプレース）に指定されたものと同じアップグレードストラテジから選択できます。

デュアルクラスターストラテジを使用してCPノードをアップグレードする。

 
flowchart TD
    DBA[(Current
    database)]
    DBB[(New 
    database)]
    CPX(Current control plane X)
    Admin(No admin 
    write operations)
    CPY(New control plane Y)
    DPX(fa:fa-layer-group Current data plane X nodes)
    API(API requests)

    DBA -.- CPX -."DP connects to either \nCP X...".- DPX
    Admin -.X.- CPX & CPY
    DBB --pg_restore--- CPY -."...OR to CP Y".- DPX
    API--> DPX

    style API stroke:none
    style DBA stroke-dasharray:3
    style CPX stroke-dasharray:3
    style Admin fill:none,stroke:none,color:#d44324
    linkStyle 2,3 stroke:#d44324,color:#d44324

図2: この図は、デュアルクラスタストラテジを使用したCPのアップグレードの流れを示しています。 新しいCP Yは現在のCP Xと一緒にデプロイされ、現在のDPノードXはまだAPIリクエストに対応しています。

インプレースストラテジを使用して CP ノードをアップグレードします。

 
flowchart 
    DBA[(Database)]
    CPX(Current control plane X \n #40;inactive#41;)
    Admin(No admin \n write operations)
    CPY(New control plane Y)
    DPX(fa:fa-layer-group Current data plane X nodes)
    API(API requests)

    DBA -..- CPX -."DP connects to either \nCP X...".- DPX
    Admin -.X.- CPX & CPY
    DBA --"kong migrations up \n kong migrations finish"--- CPY -."...OR to CP Y".- DPX
    API--> DPX

    style API stroke:none
    style CPX stroke-dasharray:3
    style Admin fill:none,stroke:none,color:#d44324
    linkStyle 2,3 stroke:#d44324,color:#d44324

図3：この図は、現在のCP Xが新しいCP Yに直接置き換えられるインプレースストラテジを使用したCPアップグレードの流れを示しています。 データベースは新しいCP Yで再利用され、すべてのノードの移行が完了すると現在のCP Xは停止されます。

2つの図から、DPノードXが現在のCPノードXに接続されたままになっているか、または新しいCPノードYに切り替わっていることがわかります。 Kong Gatewayは、CPの新しいマイナーバージョンがDPの古いマイナーバージョンと互換性があることを保証します。これにより、DPノードXが一時的に新しいCPノードYを指せるようになります。これにより、必要に応じてアップグレードプロセスを一時停止したり、より長い期間にわたってアップグレードを実行したりできます。

このセットアップは一時的なものであり、アップグレードプロセス中にのみ使用されます。長期間のプロダクションデプロイメントでは、新しいバージョンのCPノードと古いバージョンのDPノードを組み合わせて実行することはお勧めしません。

CPのアップグレード後、クラスタXを廃止することができます。この作業は、DPアップグレードの最後まで遅らせることができます。

データプレーン（DP）

CPノードがアップグレードされたら、DPノードのアップグレードに進むことができます。 DPアップグレードでサポートされている唯一のアップグレードストラテジは、ローリングアップグレードです。次の図4と5は、それぞれ図2と3に相当しています。

ローリングアップグレードのワークフローを使ったデュアルクラスタストラテジの使用：

 
flowchart TD
    DBX[(Current \n database)]
    DBY[(New \n database)]
    CPX(Current control plane X)
    CPY(New control plane Y)
    DPX(Current data planes X)
    DPY(New data planes Y)
    API(API requests)
    LB(Load balancer)
    Admin(No admin \n write operations)
    Admin2(No admin \n write operations)
    
    subgraph A
        Admin -.X.- CPX
        DBX -.- CPX
        DBY --- CPY
        CPX -."Current DP connects to \neither CP X...".- DPX
        Admin2 -.X.- CPY
        CPY -."...OR to CP Y".- DPX
        DPX -.90%..- LB
        CPY --- DPY --10%---- LB
        
    end
    subgraph B
        API --> LB & LB & LB
    end

    linkStyle 0,4 stroke:#d44324,color:#d44324
    linkStyle 8,9 stroke:#b6d7a8
    style CPX stroke-dasharray:3,fill:#eff0f1ff,stroke:#c1c6cdff
    style DPX stroke-dasharray:3
    style DBX stroke-dasharray:3,fill:#eff0f1ff,stroke:#c1c6cdff
    style API stroke:none
    style A stroke:none,color:#fff
    style B stroke:none,color:#fff
    style Admin fill:none,stroke:none,color:#d44324
    style Admin2 fill:none,stroke:none,color:#d44324

図4：デュアルクラスタとローリングストラテジを使用したDPアップグレードの図です。 新しいCP Yは現在のCP Xと一緒にデプロイされ、現在のDPノードXはまだAPIリクエストに対応しています。 画像では、現在のデータベースとCP Xの背景色が白ではなく灰色になっていますが、これは古いCPがすでにアップグレードされ、廃止された可能性があることを示しています。

ローリングアップグレードのワークフローを使ったインプレースストラテジの使用:

 
flowchart 
    DBA[(Database)]
    CPX(Current control plane X \n #40;inactive#41;)
    CPY(New control plane Y)
    DPX(Current data planes X)
    DPY(New data planes Y)
    API(API requests)
    LB(Load balancer)
    Admin(No admin \n write operations)
    Admin2(No admin \n write operations)

    subgraph A
        Admin -.X.- CPX
        DBA -.X.- CPX
        DBA --- CPY
        CPX -."Current DP connects to \neither CP X...".- DPX
        Admin2 -.X.- CPY
        CPY -."OR to CP Y".- DPX -.90%..- LB
        CPY --- DPY --10%---- LB 
    end
    subgraph B
        API --> LB & LB & LB
    end

    linkStyle 0,1,4 stroke:#d44324,color:#d44324
    linkStyle 8,9 stroke:#b6d7a8
    style CPX stroke-dasharray:3,fill:#eff0f1ff,stroke:#c1c6cdff
    style DPX stroke-dasharray:3
    style A stroke:none,color:#fff
    style B stroke:none,color:#fff
    style Admin fill:none,stroke:none,color:#d44324
    style Admin2 fill:none,stroke:none,color:#d44324

図5：インプレースとローリングストラテジを使用したDPアップグレードの図です。 この図は、データベースが新しいCP Yによって再使用される一方で、現在のDPノードXがまだAPIリクエストを処理しているところを示しています。

準備：ゲートウェイの変更を見直す

次の表は、Kong Gateway Enterprise 2.8.0.0-2.8.4.1から3.4.0.0までのすべての関連する変更ログエントリを分類したものです。各エントリを慎重に確認し、それに応じて構成を変更します。

新機能

次の表に、3.xリリースで導入された新機能を示します。これらの機能は、既存の構成に影響を与える可能性があります。

変更	カテゴリー	アクションが必要です
Request Validatorプラグイン Request Validatorプラグインは、パラメータ付きの「content-type」を持つリクエストが、パラメータなしの「content-type」とマッチすることを許可するようになりました。	プラグイン	いいえ
データプレーン（DP）構成キャッシュが削除されました。構成の永続化は、LMDB によって自動的に実行されるようになりました。データプレーン（DP）の設定キャッシュメカニズムとそれに関連する設定任意 (data_plane_config_cache_modeとdata_plane_config_cache_path) は削除され、LMDBが優先されました。	DB設定	Kong構成からパラメーターを削除します。
route.pathの変更に合わせて、宣言型構成のバージョン番号を 3.0 に上げました。古いバージョンを使用した宣言型構成は、移行中に 3.0 にアップグレードされます。	DB設定	もし設定が（GitOps モデルに従って）リポジトリに保存されているなら、deck convert を使ってアップグレードする必要があります、これらはdeck convert を使ってアップグレードする必要があります。
タグにスペースを含めることができるようになりました。	DB設定	いいえ
lua_ssl_trusted_certificateのデフォルト値がsystemに変更され、システムCAストアから信頼済みCAリストを自動的にロードするようになりました。	kong.conf	このフィールドを明示的に構成していない場合は、サーバー上のすべての証明書を自動的に取り込むという新しいデフォルト値の動作が、デプロイメントに適していることをご確認ください。それ以外の場合は、設定を調整します。
流量制限、Rate Limiting Advanced、およびResponse Rate Limitingプラグイン。これらのプラグインのデフォルトポリシーは、すべてのデプロイモードで localになりました。	プラグイン	いいえ
プラグインのバッチキューイング HTTPログ、StatsD、OpenTelemetry、Datadogプラグイン。キューイングシステムが作り直され、いくつかのプラグインパラメータが期待通りに機能しなくなりました。	プラグイン	これらのプラグインでキューを使用する場合は、新しいパラメータを構成する必要があります。詳細については、各プラグインのドキュメントをご参照ください。モジュール kong.tools.batch_queueがkong.tools.batch に変更され、APIが変更されました。カスタムプラグインがキューを使用している場合は、新しいパラメータを使用するように更新する必要があります。
3.4.3.5 以降のバージョンに適用されます。 OpenSSL 3.2では、デフォルトのSSL/TLSセキュリティレベルが1から2に変更されました。これは、セキュリティレベルが112ビットに設定されることを意味します。その結果、以下の行為は禁止されます。 2048ビット未満のRSA、DSA、DHキー 224ビットより短いECCキー RC4を使用する任意の暗号スイート SSLバージョン3 さらに、圧縮は無効になります。	OpenSSL	構成が新しいセキュリティレベル要件に準拠していることを確認します。

削除または非推奨

次の表の機能は、完全に削除されました。以下の表に基づいて設定を更新することで、非推奨のエイリアスを使用することで発生する可能性のある問題を回避し、Kongインスタンスが最新の変更と改善で正しく機能するようにすることができます。

システムの安定性、セキュリティ、最適なパフォーマンスを維持するためには、コンフィギュレーションを常に最新の状態に保つことが不可欠です。

変更	カテゴリー	アクションが必要です
Deprecated and stopped producing Debian 8 (Jessie) and Debian 10 (Buster) containers and packages.	デプロイメント	Debian 11 and 12 are available. Upgrade to one of these versions before upgrading to Kong 3.4.
Amazon Linux 1のコンテナとパッケージは非推奨となり、製造が中止された。	デプロイメント	AWSからのアップデート、セキュリティパッチ、サポートを継続的に受けるために、 Amazon Linux 2またはサポートされている他のオペレーティングシステムに移行することをお勧めします。
非推奨となり、Alpine Linuxのイメージとパッケージの生産を停止しました。便利なDockerタグの基礎となるオペレーティングシステム(OS) (例えば、`latest`、`3.4.0.0`、`3.4`）はAlpineからUbuntuに変更されました。	デプロイメント	OS 固有の構成についてDockerfileを確認し、必要に応じて調整します。便利なイメージのいずれかを使用している場合は、Ubuntu用に設定を調整してください。そうでない場合は、特定のOSタグ (例えば3.4.0.0-debian)を使ったイメージに切り替えてください。
Ubuntu 18.04 (「Bionic」) の標準サポートが2023年6月をもって終了したため、 Ubuntu 18.04 (「Bionic」) パッケージを非推奨とし、生産を停止しました。	デプロイメント	Ubuntu 20.04 および 22.04 が利用可能です。Kong 3.4 にアップグレードする前に、これらのバージョンのいずれかにアップグレードしてください。
KongプラグインやDAOスキーマの非推奨のshorthandsフィールドは削除されました。	プラグイン	カスタムスキーマでまだ「shorthands」を使用している場合は、「shorthand_fields」を使用するように更新する必要があります。このアップデートは Kongの最新バージョンとの互換性を確保するために必要です。
Kongスキーマと Kongフィールドスキーマから「legacy = true \| false」属性のサポートが削除されました。		スキーマ内でlegacy属性は使用できなくなりました。カスタムスキーマの中で「legacy=true \| false」を参照している場合は、「legacy」属性なしで最新のスキーマ仕様に適合するように更新する必要があります。
Kong.serve_admin_apiの非推奨のエイリアスが削除されました。	Nginxテンプレート	Nginxのカスタムテンプレートでエイリアスを使用している場合は、「Kong.admin_content」に変更してください。
Kongシングルトモジュールkong.singletonsPDK ‘kong.*’ を支持して削除されました。	PDK	「kong.singletons」を削除します。モジュールの代わりにkongグローバル変数を使用してください。例：’singletons.db.daos’ -> ‘kong.db.daos’
ngx.ctx.balancer_address は削除され、 ngx.ctx.balancer_dataが採用されました。	トレース	以前に ngx.ctx.balancer_address を使用していた場合、代わりに「ngx.ctx.balancer_data」を使用してください。
「route.path」の正規化ルールが変更となりました。 Kong Gatewayは正規化されていないパスを保存しますが、正規表現パスは常に正規化されたURIとパターンマッチします。以前、Kong Gatewayは、異なる形式のURIマッチを確実にするために、正規表現パスパターンでパーセントエンコーディングを置き換えていました。これはサポートされなくなりました。 RFC 3986で定義されている予約文字を除き、その他のすべての文字はパーセントエンコードなしで書き込みます。	ルーター	アップグレード後、古い方法でルートを設定するとアラートが表示され、新しいルート設定方法で影響を受けるルートを再設定する必要があります。
Kong Gateway は、ルートパスが正規表現パターンであるかどうかを推測するためにヒューリスティックを使用しなくなりました。 3.0以降では、すべての正規表現パスは接頭辞「~」で始まる必要があり、「~」で始まらないパスはすべてプレーンテキストとみなされます。	ルーター	手動での移行は必要ありません。 2.8から3.4にアップグレードすると、移行プロセスで正規表現パスが自動的に変換されるはずです。今後、正規表現を記述するときは、「~」記号で始める必要があります。
nginx-opentracingモジュールのサポートは 3.0 で非推奨となり、Kong 4.0 では削除される予定です。		いいえ
Admin API エンドポイント「/vitals/reports」と「/vitals/reports/:entity_type」が削除されました。	Admin API	アップグレード後は、代わりに Vitals API の次のいずれかのエンドポイントを使用します。 ‘/vitals/reports/consumer’ の場合は、代わりに ‘//vitals/status_codes/by_consumer' を使用 ‘/vitals/reports/service’ の場合は、代わりに ‘//vitals/status_codes/by_service' を使用 ‘/vitals/reports/hostname’ の場合は、代わりに ‘//vitals/nodes' を使用
「/targets」エンドポイントのPOSTリクエストでは、既存のエンティティを更新できなくなりました。新しいものを作ることしかできません。	Admin API	POSTリクエストを使って「/targets」を変更するスクリプトがある場合は、Kong Gateway 3.4にアップデートする前に、適切なエンドポイントへのPUTリクエストに変更してください。
‘kong.request.get_path()’PDK 関数は、呼び出し元に返される文字列に対してパスの正規化を実行するようになりました。リクエストパスの生の非正規化バージョンは、 kong.request.get_raw_path() を介して取得できます。	PDK	いいえ
`pdk.response.set_header()`,’pdk.response.set_headers()’,とpdk.response.exit ()手動で設定された Transfer Encoding ヘッダを無視して警告を出すようになりました。	PDK	いいえ
「go_pluginserver_exe」ディレクティブと「go_plugins_dir」ディレクティブはサポートされなくなりました。	Go PDK	Goプラグインサーバーを使用している場合は、アップグレードする前にプラグインを移行してGo PDKを使用するようにしてください。
X-Credential-Usernameの値を持つ Kong 定数CREDENTIAL_USERNAMEが削除されました。 Kongプラグインもこの定数をサポートしていません。	プラグイン	認証情報のアップストリームヘッダを設定する際には、定数 `CREDENTIAL_IDENTIFIER` (`X-Credential-Identifier`) を使用します。
KongのCLIツールで`.lua`形式を使用して宣言型コンフィギュレーションファイルをインポートすることができなくなりました。JSON形式とYAML形式のみがサポートされています。	宣言型構成	Kong Gatewayのアップデート手順に「Kong config db_import config.lua」の実行が含まれる場合は、アップグレードする前にconfig.luaのファイルを「config.json」または「config.yml」ファイルに変換します。
プラグイン内の DAO は、読み込み順序が明示的になるように配列にリストする必要があります。ハッシュのようなテーブルにそれらをロードすることはサポートされなくなりました。	プラグイン	カスタムプラグインを確認します。DAOをリストするためにハッシュのようなテーブルを使うプラグインがある場合、それらを配列に変換しましょう。
プラグインは「handler.lua」に有効な PRIORITY (整数) と VERSION (`x.y.z` フォーマット) フィールドを持つ必要があります。ファイルがない場合、プラグインの読み込みに失敗します。	プラグイン	カスタムプラグインを確認します。すべてのカスタムプラグインに、それぞれの形式で PRIORITY と VERSION を追加します。
‘kong.plugins.log-serializers.basic’ ライブラリは削除され、代わりに PDK 関数kong.log.serializeが導入されました。	PDK	新しいPDK機能を使用するには、プラグインをアップグレードしてください。
非推奨のレガシープラグインスキーマのサポートは削除されました。	プラグイン	カスタムプラグインがまだ古い（0.x era）スキーマを使用している場合は、それらをアップグレードする必要があります。
一部のプラグインの優先度を更新しました。プラグインが実行される順序に影響する可能性があるため、カスタムプラグインを実行する人にとって重要です。これにより、標準の Kong Gateway インストールにおけるプラグインの実行順序は変更されません。新旧のプラグイン優先度の値： acme `は` 1007 `から` 1705` に変更。 basic-auth `は` 1001 `から` 1100 `に変更。- canary` は `13` から `20` に変更。- degraphql `は` 1005 `から` 1500 `に変更。- graphql-proxy-cache-advanced` は `100` から `99` に変更。- hmac-auth `は` 1000 `から` 1030 `に変更。- jwt` は `1005` から `1450` に変更。- jwt-signer `は` 999 `から` 1020` に変更。- key-auth が 1003 から 1250 に変更されました key-auth-advanced が 1003 から 1250 に変更されました ldap-auth が 1002 から 1200 に変更されました ldap-auth-advanced が 1002 から 1200 に変更されました mtls-auth が 1006 から 1600 に変更されました oauth2 が 1004 から 1400 に変更されました openid-connect が 1000 から 1050 に変更されました rate-limiting が 901 から 910 に変更されました rate-limiting-advanced が 902 から 910 に変更されました route-by-header が 2000 から 850 に変更されました route-transformer-advanced が 800 から 780 に変更されました pre-function が +inf から 1000000 に変更されました vault-auth が 1003 から 1350 に変更されました	プラグイン	カスタムプラグインの優先順位を確認します。優先順位を変更した結果、期待された動作が損なわれた場合は、必要に応じて調整します。
JWT プラグイン認証された JWT は、Nginx コンテキスト (ngx.ctx.authenticated_jwt_token) に配置されなくなりました。	プラグイン	この名前で設定された値に依存しているカスタムプラグインは、3.4 にアップグレードする前に代わりにKongの共有コンテキスト（`kong.ctx.shared.authenticated_jwt_token`）を使うように更新する必要があります。
JWTプラグイン (jwt) JWTプラグインは、 JWTトークンの検索場所に異なるトークンがあるリクエストを拒否するようになりました。	プラグイン	いいえ
StatsD プラグインサービスに関連するメトリクス名にはすべて「service」が付くようになりました。接頭辞： ‘kong.service..request.count'です。メトリック ‘kong..request.statusは kong.service..statusに変更されました。メトリクスkong.user..request.status.は 'kong.service..user..status.に変更されました。メトリクス`status_count`と `status_count_per_user`から`.status..total が削除されました。	プラグイン	いいえ
Proxy Cache、Proxy Cache Advanced、および GraphQL Proxy Cache Advanced プラグイン。これらのプラグインはレスポンスデータを `ngx.ctx.proxy_cache_hit` に保存しません。 kong.ctx.shared.proxy_cache_hit に保存されます。	プラグイン	応答データを必要とするログプラグインは、 kong.ctx.shared.proxy_cache_hitからそれを読み取る必要があります。
デバッグ用のKong-Debugヘッダーを制限するために、 kong.confにallow_debug_header構成プロパティを追加しました。この任意のデフォルトはoffです。	DB設定	デバッグ情報を提供するためにKong-Debugヘッダーに依存していた場合は、 `allow_debug_header=on`を設定してください。ヘッダーを削除するための回避策としてResponse Transformerプラグインを使用している場合は、プラグインは必要ありません。無効にして削除します。
lua-resty-sessionライブラリが v4.0.0 にアップグレードされました。このバージョンには完全版が含まれていますセッションライブラリの書き換えで、下位互換性がありません。このライブラリは、Session、OpenID Connect、SAML などのプラグインによって使用されます。これらのプラグインで使用される多くのセッションパラメータは、名前が変更されたり削除されました。これは、セッションまたはOpenID Connectを使用するセッション構成にも影響します。 Kong Manager および Dev Portal のセッションを含む、バックグラウンドでのプラグイン。	プラグイン	このバージョンにアップグレードすると、既存のセッションはすべて無効になります。このバージョンでセッションが期待どおりに機能するには、すべてのノードで Kong Gateway 3.4.x を実行する必要があります。そのため、アップグレード中は、バージョンが混在しているプロキシノードはできるだけ短時間実行することをお勧めします。その間、無効なセッションが原因で障害が発生したり、部分的なダウンタイムが発生する可能性があります。次のような動作が予想されます。コントロールプレーンをアップグレードした後: 既存のKong ManagerとDev Portalセッションは無効になり、すべてのユーザーは再度ログインする必要があります。データプレーン（DP）をアップグレード後: 既存のプロキシセッションは無効になります。 IdP が設定されている場合、ユーザーは IdP に再度ログインする必要があります。 *すべてのCPおよびDPノードを3.4にアップグレードし、環境が安定していることを確認した後、パラメータを新しい名前に変更したバージョンに更新できます。設定は以前と同じように機能しますが、将来の予期せぬ動作を避けるため、設定を調整することをお勧めします。すべてのセッション設定の変更と、既存のセッション設定の変換方法については、下位互換性のない変更に関する書類をご確認ください。
Cassandra DB のサポートは削除されました。Kong Gateway のデータストアとしてはサポートされなくなりました。	DB設定	PostgreSQL に移行。

互換性

以下の表は、データベース設定や「kong.conf」が失敗する原因となる可能性のある動作の変更を以下に挙げています。これには、非推奨の（ただし削除されない）機能も含まれます。

変更	カテゴリー	アクションが必要です
atc-router での正規表現のルックアラウンドとバック参照のサポートが削除されました。これらはめったに使用されない機能であり、それらのサポートを削除すると、正規表現のマッチングの速度が向上します。現在使用している正規表現がルックアラウンドや後方参照を使用している場合、Kongを起動しようとすると、互換性のない正規表現を示すエラーが表示されます。	ルーター	アップグレード後の動作の一貫性を確保するために、router_flavor = traditional に設定するか、正規表現を変更してルックアラウンドや後方参照を削除してください。正規表現パスを確認し、削除された機能が使用されていないことを確認します。それに応じて正規表現ルーターを更新します。
ACL、ボット検知、IP制限プラグイン非推奨の「blacklist」と「whitelist」設定パラメータを削除しました。	プラグイン	非推奨のblacklistおよびwhitelist構成パラメータを削除します。代わりにdenylistとallowlistを使用してください。
ACME プラグイン auth_method構成パラメータのデフォルト値はtokenになりました。	プラグイン	注意：アップグレード後、`auth_method` は (この設定を利用しない場合) `null` として保持され、新しいバージョンのデフォルト設定である `token` とは異なります。
AWS Lambda プラグイン *AWSリージョンが必須になりました。aws_regionフィールドパラメータまたは環境変数を使用してプラグイン設定を通じて設定できます。プラグインでは、ホストとaws_regionフィールドを同時に設定できるようになり、常に SigV4 署名が適用されます。	プラグイン	設定を確認するか、Kongサポートチームにお問い合わせください。
HTTPログ(http-log)プラグイン headers` フィールドは、以前は値の配列を受け取っていたが、ヘッダー名ごとに単一の文字列のみを受け取るようになりました。	プラグイン	設定を確認するか、Kongサポートチームにお問い合わせください。
プロメテウスプラグインプラグインの完全なオーバーホール：カーディナリティの高いメトリクスはデフォルトで無効になりました。メトリックを収集する際のプロキシトラフィックのパフォーマンスペナルティが減少しました。以下のメトリクス名は、可能な限り標準化するために単位を追加するように調整されました： http_status `を` http_requests_total` に変更。 ‘latency’ から ‘kong_request_latency_ms’ (HTTP)、’kong_upstream_latency_ms’、’kong_kong_latency_ms’、’session_duration_ms’ (ストリーム) へ。Kong の遅延とアップストリームの遅延は、異なる大きさで動作できます。メモリのオーバーヘッドを削減するには、これらのバケットを分離します。 kong_bandwidth からkong_bandwidth_bytes 。 nginx_http_current_connectionsとnginx_stream_current_connectionsはnginx_hconnections_totalに統合されました request_countとconsumer_statusは http_requests_total に統合されました。 per_consumer設定がfalseに設定されている場合、 consumerラベルは空になります。per_consumer設定がtrueの場合、 consumerラベルが入力されます。以下のメトリクスを削除： `http_consumer_status` 新しいメトリクス： `session_duration_ms`: ストリーム接続を監視します。 node_info : ノードの ID と Kong Gateway のバージョンを出力する、1 に設定された単一のゲージ。 http_requests_totalに新しいラベルsourceが追加されました。exit 、 error 、またはserviceに設定できます。すべてのメモリメトリックに新しいラベル「node_id」が付きました。 Kongに同梱されているGrafanaダッシュボードを更新しました	プラグイン	データを見逃さないようにするには、新しい設定を使用するようにプラグインの設定を調整してください。カスタム・ダッシュボードがある場合、またはカスタムPromQLを記述している場合は、それらを確認し、名前の変更でエラーが出ていないことをご確認ください。
StatsD Advanced プラグイン StatsD Advancedプラグインは非推奨となり、4.0で削除されます。すべての機能がStatsDプラグインで利用可能になりました。	プラグイン	StatsDプラグインへの移行をお勧めしますが、StatsD Advancedは3.4でも機能します。
サーバーレス関数 (`post-function` または `pre-function`) 非推奨の `config.functions` を削除しました。 Serverless Functions プラグインのスキーマから設定パラメータを取得します。	プラグイン	「config.access」を使用し代わりにフェーズを実行します。
デフォルトの PostgreSQL SSL バージョンが TLS 1.2 に引き上げられました。「kong.conf」では：デフォルトの ‘pg_ssl_version’ は ‘tlsv1_2’ になりました。* この構成オプションの有効な値を以下のように制限しました： `tlsv1_1`、`tlsv1_2`、`tlsv1_3`、`any` これは、PostgreSQL 12.x 以降の ssl_min_protocol_version 設定を反映します。このパラメータについての詳細は[PostgreSQLドキュメント] (https://postgresqlco.nf/doc/en/param/ssl_min_protocol_version/)をご確認ください。	DB設定	「kong.conf」の値を変更するかまたは環境変数をtlsv1_0からtlsv1_2に変更します。 ‘kong.conf’ のデフォルト設定を使用するには、PostgresサーバーがTLS 1.2以上のバージョンをサポートしていることを確認するか、TLSのバージョンを自分で設定してください。 tlsv1_2`より低いTLSバージョンは既に非推奨であり、PostgreSQL 12.x以降では安全でないと考えられています。
consumer_groups/:id/overridesエンドポイントは非推奨となり、より一般的なプラグインスコープの仕組みが採用されます。	Admin API	オーバーライドを設定する代わりに、プラグイン・インスタンスをコンシューマ・グループ・エンティティに適用できます。詳しくは Rate Limiting Advanced のドキュメントをご参照ください。
admin_api_uriプロパティは非推奨となり、今後のKong Gatewayバージョンでは完全に削除される予定です。	Admin API	構成プロパティ admin_api_uriの名前を admin_gui_api_url に変更します。

相談可能

次の機能を使用するアップグレードには Kong のサポートが必要になる場合があります。

Kongのサポートチームは、データ移行、カスタムプラグインの統合、既存の設定PDKとのシームレスな連携など、特定のビジネスニーズに合わせた高度な機能とプロフェッショナルサービスを提供します。

変更	カテゴリー	アクションが必要です
3.0では、Kong Gatewayのスキーマライブラリの`process_auto_fields`関数は、与えられたコンテキストが`select`のときに渡されるデータのディープコピーを作成しません。これは、`pgmoon`や`lmdb`のようなドライバからデータが来ることが多いと思われるテーブルの過剰なディープコピーを避けるために行われました。カスタムプラグインが `process_auto_fields` に依存していた場合、与えられたテーブルをオーバーライドしないため、関数に渡す前に独自のコピーを作成する必要があります。	プラグイン	カスタムプラグインがディープコピーによってデータを取得する必要がある場合は、関数を呼び出す前に `select` コンテキストでそれを実行します。ディープコピーのトリガーとなる `context = 「select」` を定義します： `local is_select = context == "select" if not is_select then data = tablex.deepcopy(data) end`
サーバー上で利用可能な報告済みプラグインのリストは、ブール値 `true` の代わりにプラグインごとのメタデータのテーブルを返すようになりました。例： `plugins": { "available_on_server": { "acl": "3.0.1", "acme": "0.4.0", "aws-lambda": "3.6.3", "azure-functions": "1.0.1", "basic-auth": "2.2.0", "bot-detection": "2.0.0", ...`	プラグイン	ブール値の代わりに新しいメタデータを使用するように適応します。

動作の変更に関する通知

次の表には、知っておく必要はあるものの、アクションを必要としない変更点が掲載されています。

変更	カテゴリー
PDKのバージョン管理は終了しました。	PDK
移行ヘルパーライブラリ (主にカサンドラの移行に使用) は、Kong Gateway では提供されなくなりました。	DB設定
PostgreSQL の移行では、Cassandra の移行と同様に、呼び出す関数を指定する up_f 部分を持つことができるようになりました。 up_f 部分は、データベースに対して up 部分が実行された後に呼び出されます。	DB設定
Kong プラグインは個別にバージョン管理されなくなりました。 3.0.0 から、すべての Kong プラグインのバージョンが Kong Gateway のバージョンに合わせて更新されました。	プラグイン
HTTP ログプラグインログサーバーが 3xx HTTPステータスコードで応答した場合、プラグインはそれを次のように認識するようになりますエラーが発生し、再試行設定に従って再試行します。以前は、3xxのステータスコードが解釈されていましたが成功すると、ログエントリが削除されます。	プラグイン
サーバーレス関数 (ポスト関数またはプレ関数) kong.cacheキャッシュインスタンスを指している Serverless Functions プラグイン専用ですグローバル Kong Gateway キャッシュへのアクセスは提供されません。「kong.conf」の特定のフィールドへのアクセスも制限されています。	プラグイン
Zipkinプラグインこのプラグインは現在、内部バッファリングにキューを使用しています。キューイング動作を制御するために、標準キューパラメータセットを使用できます。	プラグイン

kong.confの変更

2.8	3.4
`data_plane_config_cache_mode` = 暗号化されていない	3.4で削除
`data_plane_config_cache_path`	3.4で削除
`admin_api_uri`	非推奨。代わりに`admin_gui_api_url`を使用します
`database`	使用可能な値は、`postgres` と `off` です。Cassandraオプションはすべて削除されました
`pg_keepalive_timeout = 60000`	プール内のPostgres接続の最大アイドルタイムアウト（ミリ秒単位）を指定します。この値を0に設定すると、タイムアウト間隔は無制限になります。指定しない場合、この値は`lua_socket_keepalive_timeout`と同じになります。
`worker_consistency = strict`	`worker_consistency = eventual`
`prometheus_plugin_*`	Prometheusプラグインの高カーディナリティメトリクスを無効にしました。
`lua_ssl_trusted_certificate` デフォルト値なし	デフォルト値: `lua_ssl_trusted_certificate = system`
`pg_ssl_version = tlsv1`	`pg_ssl_version = tlsv1_2`
–	`allow_debug_header = off` （新しいパラメータ）

アップグレードの実行

アップグレードストラテジを選択し、2.8と3.4 LTSリリース間の関連する変更をすべて確認しました。選択したストラテジでアップグレードを実行できます。

従来モードまたはハイブリッドモードのコントロールプレーン:

DB-lessモードまたはハイブリッドモードのデータプレーン:

ローリングアップグレード

トラブルシューティング

アップグレード中に問題が発生し、ロールバックする必要がある場合は、バックアップ方法に基づいてKong Gatewayを復元します。