旧バージョンのドキュメントを参照しています。最新のドキュメントはこちらをご参照ください。

Kong Gatewayのアップグレード

このガイドを使用して、Kong Gatewayアップグレードを準備し、使用するKong Gatewayアップグレードパスを決定します。

このガイドでは、利用可能な4つのアップグレードストラテジについて説明し、各Kong Gatewayデプロイメントモードに最適なストラテジを推奨します。さらに、アップグレードプロセスで重要な役割を果たすいくつかの基本的な要素をリストアップし、データのバックアップと復元の方法について説明します。

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

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

注：Kong Gateway Enterprise 2.8.xおよび3.4.xの長期的サポート（LTS）バージョンのアップグレードについては、LTSアップグレードガイドを参照してください。

アップグレードの概要

Kong Gatewayアップグレードには、アップグレードの準備とアップグレードの適用という2つのフェーズの作業が必要です。

準備フェーズ

以下で、プラットフォームのバージョンとアップグレード先のバージョン間のバージョン互換性を確認します。
開始するリリースとアップグレードするリリースに基づいて、アップグレードパスを決定します。
データベースまたは宣言型構成ファイルをバックアップします。
お使いのデプロイメントトポロジーに基づいて、適切なアップグレードストラテジを選択します。
アップグレードするバージョンの下位互換性のない変更を確認します。
残りのアップグレードの考慮事項があれば確認します。
運用前環境で移行をテストします。

アップグレードの実行

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

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

それでは、アップグレードパスを決定することから始めて、準備に移りましょう。

準備：アップグレードパスの確認

Kong Gatewayは、製品のバージョン管理において、メジャーバージョン、マイナーバージョン、パッチバージョンを区別する構造化されたアプローチを採用しています。

2.xから3.xへのアップグレードは、 メジャー アップグレードです。 Kong Gateway 3.0.xが移行をサポートする最も低いバージョンは、2.1.xからの移行です。

Kong Gatewayでは、1.xから3.xへの直接アップグレードをサポートしていません。 1.xを使用している場合は、まずは2.1.0にアップグレードしてください。その後、3.0.xにアップグレードしてください。

最新バージョンに直接アップグレードすることもできますが、 2.xシリーズおよび3.xシリーズ間における下位互換性のない変更（直近のバージョンと以前のバージョンの両方）およびオープンソース（OSS）と Enterpriseゲートウェイの変更ログを確認してください。Kong Gateway以降はオープンソースの基盤上に構築されているため、OSSにおける下位互換性のない変更はすべてのKong Gatewayパッケージに影響します。

アップグレードパスには広範な条件が適用され、デプロイメントモード、カスタムプラグイン、技術的機能、ハードウェア容量、SLAなどに応じて異なるため、すべてのユーザーに適用される万能のものはありません。アップグレードの際は、アクションを講じる前に、プロセスについて当社のエンジニアと網羅的かつ慎重に話し合ってください。

スムーズなアップグレードパスの維持に役立つため、Kong Gatewayリリースを常に最新の状態に保つことをお勧めします。バージョンのギャップが小さいほど、アップグレードプロセスは簡単になります。

保証されたアップグレードパス

デフォルトでは、Kong Gatewayには隣接するバージョン間の移行テストがあるため、次のアップグレードパスが正式に保証されます。

同じメジャーバージョンとマイナーバージョンのパッチリリース間。
同じメジャーバージョンの隣接するマイナーリリース間。
LTS（Long Term Support）バージョン間。

Kong GatewayはLTSバージョンを維持し、隣接するLTSバージョン間のアップグレードを保証します。 2.xシリーズの現在のLTSは2.8であり、3.xシリーズの現在のLTSは3.4です。 2.8と3.4のLTSバージョン間でアップグレードする場合は、 LTSアップグレードガイドを参照してください。

次の表は、現在使用しているKong Gatewayバージョンに応じて、3.4.xするさまざまなアップグレードパスシナリオを示しています。

現在のバージョン	トポロジー	直接アップグレードの可否	アップグレードパス
2.x–2.7.x	従来	不可	2.8.2.x にアップグレード（ブルーグリーンデプロイメントのみの場合は必須）、3.0.x にアップグレード、3.1.x にアップグレードし、3.2.x にアップグレードし、3.3.x にアップグレードし、その後、3.4.x にアップグレードします。
2.x–2.7.x	ハイブリッドモード	不可	2.8.2.xにアップグレードして、3.0.xにアップグレードし、3.1.xにアップグレードし、3.2.xにアップグレードし、3.3.xにアップグレードし、その後、3.4.xにアップグレードします。
2.x–2.7.x	DB-less	不可	3.0.xにアップグレードし、3.1.xにアップグレードし、3.2.xにアップグレードし、3.3.xにアップグレードし、その後、3.4.xにアップグレードします。
2.8.x	従来	可能	3.4.xへの直接アップグレード（LTSからLTSへのアップグレード）。
2.8.x	ハイブリッドモード	可能	3.4.xへの直接アップグレード（LTSからLTSへのアップグレード）
2.8.x	DB-less	可能	3.4.xへの直接アップグレード（LTSからLTSへのアップグレード）
3.0.x	従来	不可	3.1.xにアップグレードし、3.2.xにアップグレードし、3.3.xにアップグレードし、その後、3.4.xにアップグレードします。
3.0.x	ハイブリッドモード	不可	3.1.xにアップグレードし、3.2.xにアップグレードし、3.3.xにアップグレードし、その後、3.4.xにアップグレードします。
3.0.x	DB-less	不可	3.1.xにアップグレードし、3.2.xにアップグレードし、3.3.xにアップグレードし、その後、3.4.xにアップグレードします。
3.1.x	従来	不可	3.2.xにアップグレードし、3.3.xにアップグレードし、その後、3.4.xにアップグレードします。
3.1.0.x-3.1.1.2	ハイブリッドモード	不可	3.1.1.3 にアップグレードします。3.2.x にアップグレードし、3.3.x にアップグレードし、その後、3.4.x にアップグレードします。
3.1.1.3	ハイブリッドモード	不可	3.2.xにアップグレードし、3.3.xにアップグレードし、その後、3.4.xにアップグレードします。
3.1.x	DB-less	不可	3.2.xにアップグレードし、3.3.xにアップグレードし、その後、3.4.xにアップグレードします。
3.2.x	従来	不可	3.3.xにアップグレードし、その後、3.4.xにアップグレードします。
3.2.x	ハイブリッドモード	不可	3.3.xにアップグレードし、その後、3.4.xにアップグレードします。
3.2.x	DB-less	不可	3.3.xにアップグレードし、その後、3.4.xにアップグレードします。
3.3.x	従来	可能	3.4.x にアップグレード。
3.3.x	ハイブリッドモード	可能	3.4.x にアップグレード。
3.3.x	DB-less	可能	3.4.x にアップグレード。

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

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

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

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

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

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

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

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

独自のアップグレード手順を定義することもできますが、このセクションで紹介されている方法のいずれかを使用することをお勧めします。カスタムのアップグレード要件には、適切に調整されたアップグレード戦略が必要になる場合があります。たとえば、少数のカスタマーオブジェクトのみを新しいバージョンに送りたい場合は、トラフィックインターセプトをサポートするCanaryプラグインとロードバランサーを使用します。

どちらのアップグレードストラテジを選択する場合でも、アップグレードのプロセス中は、Admin API操作とデータベースの更新が許可されないため、 Kong Gatewayの管理ダウンタイムを考慮する必要があります。

デプロイメントタイプに基づいて、次のいずれかのアップグレードストラテジをお勧めします。各オプションの説明を注意深く読み、最適なアップグレードストラテジを選択してください。

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

 
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からのサポートは限られています。 Kong Gatewayバージョンの数、アップグレードストラテジ、採用された機能、デプロイメントモードを考慮してすべての組み合わせを網羅する必要があるため、すべての移行テストを完全に網羅することはほぼ不可能です。どうしてもこのストラテジを採用したい場合は、パッチバージョン間のアップグレードにのみ使用してください。

DBレスモード

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リクエストを処理しているところを示しています。

3.1.0.0または3.1.1.1からのアップグレード

ハイブリッドモードでKong Gatewayをデプロイし、使用しているバージョンが3.1.0.0または3.1.1.1.の場合は、特別なケースがあります。 Kongは、CPとDPの間のWebSocketプロトコルとして、3.1.0.0ではレガシー版を削除し新しいものに置き換えましたが、3.1.1.2ではレガシー版を再び追加しました。そのため、上記の特別なケースでバージョンをアップグレードする場合は、まず、3.1.1.2にアップグレードする必要があります。

さらに、新しいWebSocketプロトコルは3.2.0.0以降完全に削除されました。バージョンの内訳については、次の表を参照してください。


Kong Gatewayバージョン	従来のWebSocket（JSON）	新しいWebSocket（RPC）
3.0.0.0	Y	Y
3.1.0.0および3.1.1.1	N	Y
3.1.1.2	Y	Y
3.2.0.0	Y	N

準備：下位互換性のない変更と変更ログを確認する

アップグレード先のリリースの下位互換性のない変更と変更ログを確認します。下位互換性のない変更の指示に従って、準備または調整を行います。

準備: アップグレードに関する考慮事項

デプロイメントモードに関係なく、アップグレードに影響を与える可能性のある普遍的な要因がいくつかあります。

ターゲットデプロイメントモードのストラテジを選択しても、アップグレードをすぐに開始できるとは限りません。また、次の要素も考慮する必要があります。

アップグレードプロセス中は、データベースに変更を加えることはできません。アップグレードが完了するまで、次の行為は控えてください。
- Admin API経由でデータベースに書き込まないでください。
- データベースを直接操作しないでください。
- Kong Manager、decK、またはkong構成CLIを通じて構成を更新しないでください。
新しいバージョンYと既存のプラットフォーム間の互換性を確認します。要因には、以下が含まれますが、これらに限定されません。
現在のバージョンXから始まるすべての変更ログを注意深く確認してください。変更ログはターゲットバージョンYまであります。
- 特にスキーマの変更や機能の削除など、潜在的な競合がないか確認します。
- 新しいクラスタを設定するときは、kong.conf を直接アップグレードするか、変更履歴に基づき環境変数を使用してアップグレードします。
  
  まれに、マイナーバージョンアップグレードで kong.conf に下位互換性のない変更が行われることもあります。
  
  たとえば、パラメータpg_ssl_versionは、2.8.2.4ではデフォルトでtlsv1になります。しかし、3.2.2.1では、tlsv1は有効な引数ではありません。この設定に依存していた場合は、新しいオプションの1つに合わせて環境を調整する必要があります。
カスタムプラグインがある場合は、コードを変更ログと照合して、新しいバージョンYを使用してカスタムプラグインをテストしてください。
nginx-kong.confやnginx-kong-stream.confなどのNginxテンプレートを変更した場合は、新しいバージョンYのテンプレートにも同様の変更を加えます。詳細なカスタマイズガイドについては、Nginxディレクティブを参照してください。
Kong Gateway Enterpriseを使用している場合は、新しいゲートウェイクラスタに必ずEnterpriseライセンスを適用してください。
必ずバックアップを取ってください。
- Cassandra DBのサポートは、3.4.0.0をもってKong Gatewayから除外されました。 CassandraからPostgreSQLへの移行ガイドラインに従って、PostgreSQLに移行してください。

アップグレードの実行

すべてを確認してストラテジを選択したら、選択したストラテジを使用して Kong Gatewayのアップグレードに進みます。