このページは、まだ日本語ではご利用いただけません。翻訳中です。

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

Kong Enterprise LTS 2.8 to 3.4 upgrade guide

Kong Gateway supports direct upgrades between long-term support (LTS) versions of Kong Gateway Enterprise.

This guide walks you through upgrading from Kong Gateway Enterprise 2.8 LTS to Kong Gateway Enterprise 3.4 LTS, specifically covering 2.8.0.0-2.8.4.1 up to 3.4.0.0. Carefully review each entry and make changes to your configuration accordingly.

There are three upgrade strategies available for the LTS to LTS upgrade. This guide nominates the best applicable strategy for each deployment mode that Kong Gateway supports. Additionally, it lists some fundamental factors that play important roles in the upgrade process, and explains how to back up and recover data.

This guide uses the following terms in the context of Kong Gateway:

• Upgrade: The overall process of switching from an older to a newer version of Kong Gateway.
• Migration: The migration of your data store data into a new environment. For example, the process of moving 2.8 data from an old PostgreSQL instance to a new one for 3.4 is referred to as database migration.

To make sure your upgrade is successful, carefully review all the steps in this guide. It’s very important to understand all the preparation steps and choose the recommended upgrade path based on your deployment type.

Caution: The migration pattern described in this document can only happen between two LTS versions, Kong Gateway Enterprise 2.8 LTS and Kong Gateway Enterprise 3.4 LTS. If you apply this document to other release intervals, database modifications may be run in the wrong sequence and leave the database schema in a broken state. To migrate between other versions, see the general upgrade guide.

Prerequisites

• Starting from 3.4, Cassandra is not supported. If you’re using Cassandra as your data store, migrate off of Cassandra first and upgrade second.
• Review version compatibility between your platform version and the version of that you are upgrading to:
  • OS version
  • Kubernetes version and Helm prerequisites
• Review KIC upgrade compatibility.
• If you’re using decK, upgrade it to the latest version.

Read this document thoroughly to successfully complete the upgrade process, as it includes all the necessary operational knowledge for the upgrade.

Upgrade journey overview

Preparation phase

There are a number of steps you must complete before upgrading to Kong Gateway 3.4 LTS:

1. Work through any listed prerequisites.
2. Back up your database or your declarative configuration files.
3. Choose the right strategy for upgrading based on your deployment topology.
4. Review the Kong Gateway changes from 2.8 to 3.4 for any breaking changes that affect your deployments.
5. Conduct a thorough examination of the modifications made to the kong.conf file between the LTS releases.
6. Using your chosen strategy, test migration in a pre-production environment.

Performing the upgrade

The actual execution of the migration is dependent on the type of deployment you have with Kong Gateway. In this part of the upgrade journey, you will use the strategy you determined during the preparation phase.

1. Execute your chosen upgrade strategy on dev.
2. Move from dev to prod.
3. Smoke test.
4. Wrap up the upgrade or roll back and try again.

Now, let’s move on to preparation, starting with your backup options.

Preparation: Choose a backup strategy

The kong migrations commands used during upgrade and database migration are not reversible. Always back up your database or declarative configuration files before an upgrade.

There are two main types of backup for Kong Gateway entities:

• Database backup: PostgreSQL has native exporting and importing tools that are reliable and performant, and that ensure consistency when backing up or restoring data. If you’re running Kong Gateway in traditional or hybrid mode, you should always take a database-native backup.
• Declarative backup: Kong ships two declarative backup tools: decK and the Kong CLI, which support managing Kong Gateway entities in the declarative format. For traditional and hybrid mode deployments, use these tools to create secondary backups. For DB-less mode deployments, use the Kong CLI and manually manage declarative configuration files.

We highly recommend backing up your data using both methods if possible, as this offers you recovery flexibility.

The database-native tools are robust and can restore data instantly compared to the declarative tools. In case of data corruption, try to do a database-level restore first. Otherwise, bootstrap a new database and use declarative tools to restore configuration from backup files.

Review the Backup and Restore guide to prepare backups of your configuration. If you run into any issues and need to roll back, you can also reference that guide to restore your old data store.

Preparation: Choose an upgrade strategy based on deployment mode

Upgrade strategies introduced in this section are generic and may or may not fit in with your deployment environment.

Choose your deployment mode:

• Traditional
• DB-less
• Hybrid

Here’s a flowchart that breaks down how the decision process works:

 
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/"
  

Figure 1: Choose an upgrade strategy based on your deployment type. For traditional mode, choose a dual-cluster upgrade if you have enough resources, or an in-place upgrade if you don’t have enough resources. For DB-less mode and Konnect DPs, use a rolling upgrade. For hybrid mode, use one of the traditional mode strategies for CPs, and the rolling upgrade for DPs.

See the following sections for breakdowns of each strategy.

Traditional mode

A traditional mode deployment is when all Kong Gateway components are running in one environment, and there is no control plane/data plane separation.

You have two options when upgrading Kong Gateway in traditional mode:

• Dual-cluster upgrade: A new Kong Gateway cluster of version Y is deployed alongside the current version X, so that two clusters serve requests concurrently during the upgrade process.
• In-place upgrade: An in-place upgrade reuses the existing database and has to shut down cluster X first, then configure the new cluster Y to point to the database.

We recommend using a dual-cluster upgrade if you have the resources to run another cluster concurrently. Use the in-place method only if resources are limited, as it will cause business downtime.

Dual-cluster upgrade

Upgrading Kong Gateway from one LTS version to another LTS version with zero downtime can be achieved through a dual-cluster upgrade strategy. This approach involves setting up a new cluster running the upgraded version of Kong Gateway alongside the existing cluster running the current version.

At a high level, the process typically involves the following steps:

1. Provisioning a same-size deployment: You need to ensure that the new cluster, which will run the upgraded version of Kong Gateway, has the same capacity and resources as the existing cluster. This ensures that both clusters can handle the same amount of traffic and workload.

2. Setting up dual-cluster deployment: Once the new cluster is provisioned, you can start deploying your APIs and configurations to both clusters simultaneously. The dual cluster deployment allows both the old and new clusters to coexist and process requests in parallel.

3. Data synchronization: During the dual cluster deployment, data synchronization is crucial to ensure that both clusters have the same data. This can involve migrating data from the old cluster to the new one or setting up a shared data storage solution to keep both clusters in sync. Import the database from the old cluster to the new cluster by using a snapshot or pg_restore.

4. Traffic rerouting: As the new cluster is running alongside the old one, you can start gradually routing incoming traffic to the new cluster. This process can be done gradually or through a controlled switchover mechanism to minimize any impact on users. This can be achieved by any load balancer, like DNS, Nginx, F5, or even a Kong Gateway node with Canary plugin enabled.

5. Testing and validation: Before performing a complete switchover to the new cluster, it is essential to thoroughly test and validate the functionality of the upgraded version. This includes testing APIs, plugins, authentication mechanisms, and other functionalities to ensure they are working as expected.

6. Complete switchover: Once you are confident that the upgraded cluster is fully functional and stable, you can redirect all incoming traffic to the new cluster. This step completes the upgrade process and decommissions the old cluster.

By following this dual cluster deployment strategy, you can achieve a smooth and zero-downtime upgrade from one LTS version of Kong Gateway to another. This approach helps ensure high availability and uninterrupted service for your users throughout the upgrade process.

In-place upgrade

While an in-place upgrade allows you to perform the upgrade on the same infrastructure, it does require some downtime during the actual upgrade process. Plan a suitable maintenance or downtime window during which you can perform the upgrade. During this period, the Kong Gateway will be temporarily unavailable.

For scenarios where zero downtime is critical, consider the dual-cluster upgrade method, keeping in mind the additional resources and complexities.

DB-less mode

In DB-less mode, each independent Kong Gateway node loads a copy of declarative Kong Gateway configuration data into memory without persistent database storage, so failure of some nodes doesn’t spread to other nodes.

Deployments in this mode should use the rolling upgrade strategy. You could parse the validity of the declarative YAML contents with version Y, using the deck gateway validate or the kong config parse command.

You must back up your current kong.yaml file before starting the upgrade.

Hybrid mode

Hybrid mode comprises of one or more control plane (CP) nodes, and one or more data plane (DP) nodes. CP nodes use a database to store Kong configuration data, whereas DP nodes don’t, since they get all of the needed information from the CP. The recommended upgrade process is a combination of different upgrade strategies for each type of node, CP or DP.

The major challenge with a hybrid mode upgrade is the communication between the CP and DP. As hybrid mode requires the minor version of the CP to be no less than that of the DP, you must upgrade CP nodes before DP nodes. The upgrade must be carried out in two phases:

1. First, upgrade the CP according to the recommendations in the section Traditional Mode, while DP nodes are still serving API requests.
2. Next, upgrade DP nodes using the recommendations from the section DB-less Mode. Point the new DP nodes to the new CP to avoid version conflicts.

The role decoupling feature between CP and DP enables DP nodes to serve API requests while upgrading CP. With this method, there is no business downtime.

Custom plugins (either your own plugins or third-party plugins that are not shipped with Kong Gateway) need to be installed on both the control plane and the data planes in hybrid mode. Install the plugins on the control plane first, and then the data planes.

See the following sections for a breakdown of the options for hybrid mode deployments.

Control planes

CP nodes must be upgraded before DP nodes. CP nodes serve an admin-only role and require database support. So, you can select from the same upgrade strategies nominated for traditional mode (dual-cluster or in-place), as described in figure 2 and figure 3 respectively.

Upgrading the CP nodes using the dual-cluster strategy:

 
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
  

Figure 2: The diagram shows a CP upgrade using the dual-cluster strategy. The new CP Y is deployed alongside the current CP X, while current DP nodes X are still serving API requests.

Upgrading the CP nodes using the in-place strategy:

 
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
  

Figure 3: The diagram shows a CP upgrade using the in-place strategy, where the current CP X is directly replaced by a new CP Y. The database is reused by the new CP Y, and the current CP X is shut down once all nodes are migrated.

From the two figures, you can see that DP nodes X remain connected to the current CP node X, or alternatively switch to the new CP node Y. Kong Gateway guarantees that new minor versions of CPs are compatible with old minor versions of the DP, so you can temporarily point DP nodes X to the new CP node Y. This lets you pause the upgrade process if needed, or conduct it over a longer period of time.

This setup is meant to be temporary, to be used only during the upgrade process. We do not recommend running a combination of new versions of CP nodes and old versions of DP nodes in a long-term production deployment.

After the CP upgrade, cluster X can be decommissioned. You can delay this task to the very end of the DP upgrade.

Data planes

Once the CP nodes are upgraded, you can move on to upgrade the DP nodes. The only supported upgrade strategy for DP upgrades is the rolling upgrade. The following diagrams, figure 4 and 5, are the counterparts of figure 2 and 3 respectively.

Using the dual-cluster strategy with a rolling upgrade workflow:

 
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
  

Figure 4: The diagram shows a DP upgrade using the dual-cluster and rolling strategies. The new CP Y is deployed alongside with the current CP X, while current DP nodes X are still serving API requests. In the image, the background color of the current database and CP X is grey instead of white, signaling that the old CP is already upgraded and might have been decommissioned.

Using the in-place strategy strategy with a rolling upgrade workflow:

 
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
  

Figure 5: The diagram shows a DP upgrade using the in-place and rolling strategies. The diagram shows that the database is reused by the new CP Y, while current DP nodes X are still serving API requests.

Preparation: Review gateway changes

The following tables categorize all relevant changelog entries from Kong Gateway Enterprise 2.8.0.0-2.8.4.1 up to 3.4.0.0. Carefully review each entry and make changes to your configuration accordingly.

新機能

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

削除または非推奨

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

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

互換性

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

相談可能

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

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

local is_select = context == "select"
  if not is_select then
    data = tablex.deepcopy(data)
end

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",
  ...

動作の変更に関する通知

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

kong.conf changes

Perform upgrade

Now that you have chosen an upgrade strategy, reviewed all the relevant changes between the 2.8 and 3.4 LTS releases you can move on to performing the upgrade with your chosen strategy:

Traditional mode or control planes in hybrid mode:

• Dual-cluster upgrade
• In-place upgrade

DB-less mode or data planes in hybrid mode:

• Rolling upgrade

Troubleshooting

If you run into issues during the upgrade and need to roll back, restore Kong Gateway based on the backup method.