コンテンツにスキップ
Kong Logo | Kong Docs Logo
  • ドキュメント
    • API仕様を確認する
      View all API Specs すべてのAPI仕様を表示 View all API Specs arrow image
    • ドキュメンテーション
      API Specs
      Kong Gateway
      軽量、高速、柔軟なクラウドネイティブAPIゲートウェイ
      Kong Konnect
      SaaSのエンドツーエンド接続のための単一プラットフォーム
      Kong AI Gateway
      GenAI インフラストラクチャ向けマルチ LLM AI Gateway
      Kong Mesh
      Kuma と Envoy をベースにしたエンタープライズサービスメッシュ
      decK
      Kongの構成を宣言型で管理する上で役立ちます
      Kong Ingress Controller
      Kubernetesクラスタ内で動作し、Kongをプロキシトラフィックに設定する
      Kong Gateway Operator
      YAMLマニフェストを使用してKubernetes上のKongデプロイメントを管理する
      Insomnia
      コラボレーティブAPI開発プラットフォーム
  • Plugin Hub
    • Plugin Hubを探索する
      View all plugins すべてのプラグインを表示 View all plugins arrow image
    • 機能性 すべて表示 View all arrow image
      すべてのプラグインを表示
      AI's icon
      AI
      マルチ LLM AI Gatewayプラグインを使用してAIトラフィックを管理、保護、制御する
      認証's icon
      認証
      認証レイヤーでサービスを保護する
      セキュリティ's icon
      セキュリティ
      追加のセキュリティレイヤーでサービスを保護する
      トラフィック制御's icon
      トラフィック制御
      インバウンドおよびアウトバウンドAPIトラフィックの管理、スロットル、制限
      サーバーレス's icon
      サーバーレス
      他のプラグインと組み合わせてサーバーレス関数を呼び出します
      分析と監視's icon
      分析と監視
      APIとマイクロサービストラフィックを視覚化、検査、監視
      変革's icon
      変革
      Kongでリクエストとレスポンスをその場で変換
      ログ記録's icon
      ログ記録
      インフラストラクチャに最適なトランスポートを使用して、リクエストと応答データをログに記録します
  • サポート
  • コミュニティ
  • Kongアカデミー
デモを見る 無料トライアルを開始
Kong Gateway
2.8.x LTS
  • Home icon
  • Kong Gateway
  • Install And Run
  • Upgrade Kong Gateway
report-issue問題を報告する
  • Kong Gateway
  • Kong Konnect
  • Kong Mesh
  • Kong AI Gateway
  • Plugin Hub
  • decK
  • Kong Ingress Controller
  • Kong Gateway Operator
  • Insomnia
  • Kuma

  • ドキュメント投稿ガイドライン
  • 3.10.x (latest)
  • 3.9.x
  • 3.8.x
  • 3.7.x
  • 3.6.x
  • 3.5.x
  • 3.4.x (LTS)
  • 3.3.x
  • 2.8.x (LTS)
  • アーカイブ (2.6より前)
  • Introduction
    • Overview of Kong Gateway
    • Version Support Policy
    • Stages of Software Availability
    • Changelog
  • Install and Run
    • Overview
    • Kubernetes
    • Helm
    • OpenShift with Helm
    • Docker
    • Amazon Linux
    • CentOS
    • Debian
    • RHEL
    • Ubuntu
    • Migrating from OSS to EE
    • Upgrade Kong Gateway
    • Upgrade Kong Gateway OSS
    • Upgrade from 2.8 LTS to 3.4 LTS
  • Get Started
    • Quickstart Guide
      • Configuring a Service
      • Configuring a gRPC Service
      • Enabling Plugins
      • Adding Consumers
    • Comprehensive Guide
      • Prepare to Administer
      • Expose your Services
      • Protect your Services
      • Improve Performance
      • Secure Services
      • Set Up Intelligent Load Balancing
      • Manage Administrative Teams
      • Publish, Locate, and Consume Services
  • Plan and Deploy
    • Running Kong as a Non-Root User
    • Resource Sizing Guidelines
    • Hybrid Mode
      • Deploy Kong Gateway in Hybrid Mode
    • Kubernetes Deployment Options
    • Control Kong Gateway through systemd
    • Performance Testing Framework
    • DNS Considerations
    • Default Ports
    • Licenses
      • Access Your License
      • Deploy Your License
      • Monitor License Usage
    • Security
      • Start Kong Gateway Securely
      • Keyring and Data Encryption
      • Kong Security Update Process
      • Secrets Management
        • Getting Started
        • Advanced Usage
        • Backends
          • Environment Variables
          • AWS Secrets Manager
          • GCP Secret Manager
          • HashiCorp Vault
        • Reference Format
  • Configure
    • Authentication and Authorization
      • Authentication Reference
      • OpenID Connect Plugin
        • OpenID Connect with Curity
        • OpenID Connect with Azure AD
        • OpenID Connect with Google
        • OpenID Connect with Okta
        • OpenID Connect with Auth0
        • OpenID Connect with Cognito
        • OpenID Connect Plugin Reference
      • Allowing Multiple Authentication Methods
      • Auth for Kong Manager
        • Create a Super Admin
        • Configure Networking
        • Configure Kong Manager to Send Email
        • Reset Passwords and RBAC Tokens
        • Configure Workspaces
        • Basic Auth
        • LDAP
        • OIDC
        • Sessions
      • Role-based Access Control (RBAC)
        • Add a Role
        • Add a User
        • Add an Admin
      • Mapping LDAP Service Directory Groups to Kong Roles
    • Configure gRPC Plugins
    • GraphQL Quickstart
    • Logging Reference
    • Network and Firewall
  • Dev Portal
    • Overview
    • Enable the Dev Portal
    • Structure and File Types
    • Portal API Documentation
    • Working with Templates
    • Using the Editor
    • Configuration
      • Authentication
        • Basic Auth
        • Key Auth
        • OIDC
        • Sessions
        • Adding Custom Registration Fields
      • SMTP
      • Workspaces
    • Administration
      • Manage Developers
      • Developer Roles and Content Permissions
      • Application Registration
        • Authorization Provider Strategy
        • Enable Application Registration
        • Enable Key Authentication for Application Registration
        • External OAuth2 Support
        • Set up Okta and Kong for external OAuth
        • Set Up Azure AD and Kong for External Authentication
        • Manage Applications
    • Customization
      • Easy Theme Editing
      • Migrating Templates Between Workspaces
      • Markdown Rendering Module
      • Customizing Portal Emails
      • Adding and Using JavaScript Assets
      • Single Page App in Dev Portal
      • Alternate OpenAPI Renderer
    • Helpers CLI
  • Monitor
    • Kong Vitals
      • Metrics
      • Reports
      • Vitals with InfluxDB
      • Vitals with Prometheus
      • Estimate Vitals Storage in PostgreSQL
    • Prometheus plugin
    • Zipkin plugin
  • Reference
    • Admin API
      • DB-less Mode
      • Declarative Configuration
      • Supported Content Types
      • Information Routes
      • Health Routes
      • Tags
      • Service Object
      • Route Object
      • Consumer Object
      • Plugin Object
      • Certificate Object
      • CA Certificate Object
      • SNI Object
      • Upstream Object
      • Target Object
      • Vaults Beta
      • Licenses
        • Licenses Reference
        • Licenses Examples
      • Workspaces
        • Workspaces Reference
        • Workspace Examples
      • RBAC
        • RBAC Reference
        • RBAC Examples
      • Admins
        • API Reference
        • Examples
      • Developers
      • Consumer Groups
        • API Reference
        • Examples
      • Event Hooks
        • Event Hooks Reference
        • Examples
      • Audit Logging
      • Keyring and Data Encryption
      • Securing the Admin API
    • DB-less and Declarative Configuration
    • Configuration Reference
    • CLI Reference
    • Load Balancing Reference
    • Proxy Reference
    • Rate Limiting Library
    • Health Checks and Circuit Breakers Reference
    • Clustering Reference
    • Plugin Development Kit
      • kong.client
      • kong.client.tls
      • kong.cluster
      • kong.ctx
      • kong.ip
      • kong.log
      • kong.nginx
      • kong.node
      • kong.request
      • kong.response
      • kong.router
      • kong.service
      • kong.service.request
      • kong.service.response
      • kong.table
      • kong.vault
    • Plugin Development Guide
      • Introduction
      • File structure
      • Implementing custom logic
      • Plugin configuration
      • Accessing the datastore
      • Storing custom entities
      • Caching custom entities
      • Extending the Admin API
      • Writing tests
      • (un)Installing your plugin
    • Plugins in Other Languages
    • File Permissions Reference
enterprise-switcher-icon 次に切り替える: OSS
On this pageOn this page
  • Upgrade path for Kong Gateway releases
  • Upgrade considerations
    • Kong Manager breaking changes
    • Dev Portal migrations
    • Hybrid mode considerations
    • Kong for Kubernetes considerations
  • Upgrade from 1.x.x - 2.7.x to 2.8.x
    • PostgreSQL
    • Cassandra
    • Install 2.8.x on a fresh datastore

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

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

Upgrade Kong Gateway

Upgrade to major, minor, and patch Kong Gateway Enterprise (Enterprise package) releases using the kong migrations commands.

You can also use the commands to migrate all Kong Gateway (OSS) entities to Kong Gateway Enterprise. See Migrating from Kong Gateway (OSS) to Kong Gateway.

If you experience any issues when running migrations, contact Kong Support for assistance.

Upgrade path for Kong Gateway releases

Kong follows a structured approach to versioning its products, which makes a distinction between major, minor, and patch versions. The upgrade path for major and minor versions differs depending on the previous version from which you are migrating:

  • If you are migrating from 2.x.x, upgrading to 2.8.x is a minor upgrade. You can upgrade from any 2.1.x or later version directly to 2.8.x.

  • If you are migrating from 1.x.x, upgrading to 2.8.x is a major upgrade. While you can upgrade directly to the latest version, be aware of any breaking changes between the 1.x and 2.x series noted in this document (both this version and prior versions) and in the Gateway changelogs.

    See specific breaking changes in the Kong Gateway changelogs: open-source (OSS) and Enterprise. Since Kong Gateway is built on an open-source foundation, any breaking changes in OSS affect all Gateway packages.

In either case, you can review the upgrade considerations, then follow the database migration instructions.

Upgrade considerations

Before upgrading, review this list for any configuration or breaking changes that affect your current installation.

If you are adding a new plugin to your installation, you need to run kong migrations up with the plugin name specified. For example, KONG_PLUGINS=oauth2.

Kong Manager breaking changes

Version 2.7.x introduced a new way to configure the OIDC plugin to map IdP roles to Kong Manager admin accounts.

If you are upgrading from 2.6.x or earlier, you must now specify the admin_claim instead of the consumer_claim in your OIDC config file. For more information, see OIDC Authenticated Group Mapping.

Dev Portal migrations

There are no migrations necessary for the Dev Portal when upgrading from 2.7.x to 2.8.x.

If you are currently using the Dev Portal in 1.5.x or earlier, manually migrate the files to version 2.1.x before continuing.

Hybrid mode considerations

Important: If you are currently running in hybrid mode, upgrade the control plane first, and then the data planes.

  • If you are currently running 2.7.x in classic (traditional) mode and want to run in hybrid mode instead, follow the hybrid mode installation instructions after running the migration.
  • Custom plugins (either your own plugins or third-party plugins that are not shipped with Kong) 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.
  • The Rate Limiting Advanced plugin does not support the cluster strategy in hybrid mode. The redis strategy must be used instead.

Kong for Kubernetes considerations

The Helm chart automates the upgrade migration process. When running helm upgrade, the chart spawns an initial job to run kong migrations up and then spawns new Kong pods with the updated version. Once these pods become ready, they begin processing traffic and old pods are terminated. Once this is complete, the chart spawns another job to run kong migrations finish.

While the migrations themselves are automated, the chart does not automatically ensure that you follow the recommended upgrade path. If you are upgrading from more than one minor Kong version back, check the upgrade path recommendations for Kong open source or Kong Gateway.

Although not required, users should upgrade their chart version and Kong version independently. In the event of any issues, this will help clarify whether the issue stems from changes in Kubernetes resources or changes in Kong.

For specific Kong for Kubernetes version upgrade considerations, see Upgrade considerations

Kong deployment split across multiple releases

The standard chart upgrade automation process assumes that there is only a single Kong release in the Kong cluster, and runs both migrations up and migrations finish jobs.

If you split your Kong deployment across multiple Helm releases (to create proxy-only and admin-only nodes, for example), you must set which migration jobs run based on your upgrade order.

To handle clusters split across multiple releases, you should:

  1. Upgrade one of the releases with:

    helm upgrade RELEASENAME -f values.yaml \
    --set migrations.preUpgrade=true \
    --set migrations.postUpgrade=false
    
  2. Upgrade all but one of the remaining releases with:

    helm upgrade RELEASENAME -f values.yaml \
    --set migrations.preUpgrade=false \
    --set migrations.postUpgrade=false
    
  3. Upgrade the final release with:

    helm upgrade RELEASENAME -f values.yaml \
    --set migrations.preUpgrade=false \
    --set migrations.postUpgrade=true
    

This ensures that all instances are using the new Kong package before running kong migrations finish.

Upgrade from 1.x.x - 2.7.x to 2.8.x

Kong Gateway Enterprise supports the zero downtime migration model. This means that while the migration is in process, you have two Kong clusters with different versions running that are sharing the same database. This is sometimes referred to as the blue-green migration model.

The migrations are designed so that there is no need to fully copy the data. The new version of Kong Gateway Enterprise is able to use the data as it is migrated, and the old Kong cluster keeps working until it is finally time to decommission it. For this reason, the full migration is split into two commands:

  • kong migrations up: performs only non-destructive operations
  • kong migrations finish: puts the database in the final expected state (DB-less mode is not supported in Kong Gateway Enterprise)

Follow the instructions for your backing data store to migrate to the new version. If you prefer to use a fresh data store and only migrate your kong.conf file, see the instructions to install 2.8.x on a fresh datastore.

PostgreSQL

  1. Download 2.8.x, and configure it to point to the same datastore as your old (1.x.x-2.x.x) cluster.
  2. Run kong migrations up.
  3. After that finishes running, both the old (1.x.x-2.x.x) and new (2.8.x) clusters can now run simultaneously on the same datastore. Start provisioning 2.8.x nodes, but do not use their Admin API yet.

    Important: If you need to make Admin API requests, these should be made to the old cluster’s nodes. This prevents the new cluster from generating data that is not understood by the old cluster.

  4. Gradually divert traffic away from your old nodes, and redirect traffic to your 2.8.x cluster. Monitor your traffic to make sure everything is going smoothly.
  5. When your traffic is fully migrated to the 2.8.x cluster, decommission your old nodes.
  6. From your 2.8.x cluster, run kong migrations finish. From this point onward, it is no longer possible to start nodes in the old cluster that still points to the same datastore.

    Run this command only when you are confident that your migration was successful. From now on, you can safely make Admin API requests to your 2.8.x nodes.

Cassandra

Due to internal changes, the table schemas used by Kong Gateway Enterprise 2.8.x on Cassandra are incompatible with those used by Kong Gateway Enterprise 2.1.x or lower. Migrating using the usual commands kong migrations up and kong migrations finish will require a small window of downtime, since the old and new versions cannot use the database at the same time.

Alternatively, to keep your previous version fully operational while the new one initializes, transfer the data to a new keyspace using a database dump, as described below:

  1. Download 2.8.x, and configure it to point to a new keyspace.

  2. Run kong migrations bootstrap.

    Once that finishes running, both the old (1.x.x-2.1.x) and new (2.8.x) clusters can now run simultaneously, but the new cluster does not have any data yet.

  3. On the old cluster, run kong config db_export. This will create a file named kong.yml with a database dump.
  4. Transfer the file to the new cluster and run kong config db_import kong.yml. This will load the data into the new cluster.
  5. Gradually divert traffic away from your old nodes, and into your 2.7.x cluster. Monitor your traffic to make sure everything is going smoothly.
  6. When your traffic is fully migrated to the 2.8.x cluster, decommission your old nodes.

Install 2.8.x on a fresh datastore

For installing on a fresh datastore, Kong Gateway Enterprise 2.8.x has the kong migrations bootstrap command. Run the following commands to prepare a new 2.8.x cluster from a fresh datastore. By default, the kong CLI tool loads the configuration from /etc/kong/kong.conf, but you can optionally use the -c flag to indicate the path to your configuration file:

$ kong migrations bootstrap [-c /path/to/kong.conf]
$ kong start [-c /path/to/kong.conf]
Thank you for your feedback.
Was this page useful?
情報が多すぎる場合 close cta icon
Kong Konnectを使用すると、より多くの機能とより少ないインフラストラクチャを実現できます。月額1Mリクエストが無料。
無料でお試しください
  • Kong
    APIの世界を動かす

    APIマネジメント、サービスメッシュ、イングレスコントローラーの統合プラットフォームにより、開発者の生産性、セキュリティ、パフォーマンスを大幅に向上します。

    • 製品
      • Kong Konnect
      • Kong Gateway Enterprise
      • Kong Gateway
      • Kong Mesh
      • Kong Ingress Controller
      • Kong Insomnia
      • 製品アップデート
      • 始める
    • ドキュメンテーション
      • Kong Konnectドキュメント
      • Kong Gatewayドキュメント
      • Kong Meshドキュメント
      • Kong Insomniaドキュメント
      • Kong Konnect Plugin Hub
    • オープンソース
      • Kong Gateway
      • Kuma
      • Insomnia
      • Kongコミュニティ
    • 会社概要
      • Kongについて
      • お客様
      • キャリア
      • プレス
      • イベント
      • お問い合わせ
  • 利用規約• プライバシー• 信頼とコンプライアンス
© Kong Inc. 2025