Skip to content
2023 API Summit Hackathon: Experiment with AI for APIs (August 28 - September 27) Learn More →
Kong Logo | Kong Docs Logo
search
  • We're Hiring!
  • Docs
    • Kong Gateway
      Lightweight, fast, and flexible cloud-native API gateway
      Kong Konnect
      Single platform for SaaS end-to-end connectivity
      Kong Mesh
      Enterprise service mesh based on Kuma and Envoy
      decK
      Helps manage Kong’s configuration in a declarative fashion
      Kong Ingress Controller
      Works inside a Kubernetes cluster and configures Kong to proxy traffic
      Insomnia
      Collaborative API development platform
      Kuma
      Open-source distributed control plane with a bundled Envoy Proxy integration
      Docs Contribution Guidelines
      Want to help out, or found an issue in the docs and want to let us know?
  • API Specs
  • Plugin Hub
    • Explore the Plugin Hub
      View all plugins View all plugins View all plugins arrow image
    • Functionality View all View all arrow image
      View all plugins
      Authentication's icon
      Authentication
      Protect your services with an authentication layer
      Security's icon
      Security
      Protect your services with additional security layer
      Traffic Control's icon
      Traffic Control
      Manage, throttle and restrict inbound and outbound API traffic
      Serverless's icon
      Serverless
      Invoke serverless functions in combination with other plugins
      Analytics & Monitoring's icon
      Analytics & Monitoring
      Visualize, inspect and monitor APIs and microservices traffic
      Transformations's icon
      Transformations
      Transform request and responses on the fly on Kong
      Logging's icon
      Logging
      Log request and response data using the best transport for your infrastructure
  • Support
  • Community
  • Kong Academy
Get a Demo Start Free Trial
Kong Gateway
3.4.x (latest)
  • Home icon
  • Kong Gateway
  • Upgrade Kong Gateway 3.x.x
github-edit-pageEdit this page
report-issueReport an issue
  • Kong Gateway
  • Kong Konnect
  • Kong Mesh
  • Plugin Hub
  • decK
  • Kong Ingress Controller
  • Insomnia
  • Kuma

  • Docs contribution guidelines
  • 3.4.x (latest)
  • 3.3.x
  • 3.2.x
  • 3.1.x
  • 3.0.x
  • 2.8.x
  • 2.7.x
  • 2.6.x
  • Archive (pre-2.6)
enterprise-switcher-icon Switch to OSS
On this pageOn this page
  • Upgrade path for Kong Gateway releases
  • Upgrade path for Kong Gateway 3.4.x
  • General upgrade path
    • Traditional mode
    • Hybrid mode
  • Upgrade to Kong Gateway 3.x.x and retain 2.x.x alerts for Prometheus

Upgrade Kong Gateway 3.x.x

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

You can also use the commands to migrate all Kong Gateway open-source 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 adheres to semantic versioning, which makes a distinction between major, minor, and patch versions.

The upgrade to 3.4.x is a minor upgrade.

Important: Blue-green migration in traditional mode for versions below 2.8.2 to 3.0.x is not supported. The 2.8.2 release includes blue-green migration support. If you want to perform migrations for traditional mode with no downtime, upgrade to 2.8.2, then migrate to 3.4.x.

While you can upgrade directly to the latest version, be aware of any breaking changes between the 2.x and 3.x series noted in this document (both this version and prior versions) and in the open-source (OSS) and Enterprise Gateway changelogs. Since Kong Gateway is built on an open-source foundation, any breaking changes in OSS affect all Kong Gateway packages.

Kong Gateway does not support directly upgrading from 1.x to 3.4.x. If you are running 1.x, upgrade to 2.8.2 first and then to 3.0.x and 3.1.x at a minimum. Finally, upgrade to 3.4.x from there.

In either case, you can review the breaking changes for your version, then follow the database migration instructions.

Upgrade path for Kong Gateway 3.4.x

The following table outlines various upgrade path scenarios to 3.4.x depending on the Kong Gateway version you are currently using:

Current version Topology Direct upgrade possible? Upgrade path
2.x–2.7.x Traditional No Upgrade to 2.8.2.x (required for blue/green deployments only), upgrade to 3.0.x, upgrade to 3.1.x, upgrade to 3.2.x, upgrade to 3.3.x, and then upgrade to 3.4.x.
2.x–2.7.x Hybrid No Upgrade to 2.8.2.x, upgrade to 3.0.x, upgrade to 3.1.x, upgrade to 3.2.x, upgrade to 3.3.x, and then upgrade to 3.4.x.
2.x–2.7.x DB less No Upgrade to 3.0.x, upgrade to 3.1.x, upgrade to 3.2.x, upgrade to 3.3.x, and then upgrade to 3.4.x.
2.8.x Traditional No Upgrade to 3.1.1.3, upgrade to 3.2.x, upgrade to 3.3.x, and then upgrade to 3.4.x.
2.8.x Hybrid No Upgrade to 3.1.1.3, upgrade to 3.2.x, upgrade to 3.3.x, and then upgrade to 3.4.x.
2.8.x DB less No Upgrade to 3.1.1.3, upgrade to 3.2.x, upgrade to 3.3.x, and then upgrade to 3.4.x.
3.0.x Traditional No Upgrade to 3.1.x, upgrade to 3.2.x, upgrade to 3.3.x, and then upgrade to 3.4.x.
3.0.x Hybrid No Upgrade to 3.1.x, upgrade to 3.2.x, upgrade to 3.3.x, and then upgrade to 3.4.x.
3.0.x DB less No Upgrade to 3.1.x, upgrade to 3.2.x, upgrade to 3.3.x, and then upgrade to 3.4.x.
3.1.x Traditional No Upgrade to 3.2.x, upgrade to 3.3.x, and then upgrade to 3.4.x.
3.1.0.x-3.1.1.2 Hybrid No Upgrade to 3.1.1.3, upgrade to 3.2.x, upgrade to 3.3.x, and then upgrade to 3.4.x.
3.1.1.3 Hybrid No Upgrade to 3.2.x, upgrade to 3.3.x, and then upgrade to 3.4.x.
3.1.x DB less No Upgrade to 3.2.x, upgrade to 3.3.x, and then upgrade to 3.4.x.
3.2.x Traditional No Upgrade to 3.3.x, and then upgrade to 3.4.x.
3.2.x Hybrid No Upgrade to 3.3.x, and then upgrade to 3.4.x.
3.2.x DB less No Upgrade to 3.3.x, and then upgrade to 3.4.x.
3.3.x Traditional Yes Upgrade to 3.4.x.
3.3.x Hybrid Yes Upgrade to 3.4.x.
3.3.x DB less Yes Upgrade to 3.4.x.

General upgrade path

Running kong migrations in this workflow is irrevocable, therefore we recommend that you backup data before making any changes.

A database dump is recommended so that you can recover from migrations failure at the database level.

Additionally, Kong Gateway supports exporting data in YAML format with kong config db_export, which later on can be imported back by kong config db_import. For more information, see kong config CLI.

Traditional mode

  1. Clone your database.
  2. Download the version of Kong Gateway you want to upgrade to, and configure it to point to the cloned data store. Run kong migrations up and kong migrations finish.
  3. Start the new Kong Gateway version cluster.
  4. Now both the old and new clusters can now run simultaneously. Start provisioning the new Kong Gateway version nodes.
  5. Gradually divert traffic away from your old nodes, and into your new cluster. Monitor your traffic to make sure everything is going smoothly.
  6. When your traffic is fully migrated to the new cluster, decommission your old nodes.

Hybrid mode

Do not make any changes to Kong configuration (kong.conf) or use the Admin API in the middle of an upgrade. This can cause incompatibilities between data plane nodes.

Perform a rolling upgrade of your cluster:

  1. Download the version of Kong Gateway you want to upgrade to.
  2. Decommission your existing control plane. Your existing data planes can continue to handle proxy traffic during this time, even with no active control plane.
  3. Configure the new Kong Gateway version control plane to point to the same data store as your old control plane. Run kong migrations up and kong migrations finish.
  4. Start the new control plane.
  5. Start new data planes.
  6. Gradually divert traffic away from your old data planes, and into the new data planes. Monitor your traffic to make sure everything is going smoothly.
  7. When your traffic is fully migrated to the new cluster, decommission your old data planes.

Upgrade to Kong Gateway 3.x.x and retain 2.x.x alerts for Prometheus

You can upgrade to Kong Gateway 3.x.x while still retaining your Kong Gateway 2.x.x Prometheus alerts or dashboards. This can be useful if you don’t have the capacity to patch them to comply with the new Kong Gateway 3.x.x Prometheus metrics.

Convert Kong Gateway 3.x.x Prometheus metrics into Kong Gateway 2.x.x Prometheus metrics in the kong.config file:

- job_name: kong-3x-metrics-as-kong-2x
  scrape_interval: 20s
  scrape_timeout: 19s
  metrics_path: /metrics
  scheme: http
  metric_relabel_configs:
    - action: replace
      source_labels:
        - __name__
      regex: kong_http_requests_total
      target_label: __name__
      replacement: kong_http_status

    - action: replace
      source_labels:
        - __name__
      regex: kong_(.*)_latency_ms_(bucket|count|sum)
      target_label: type
      replacement: $1
    - action: replace
      source_labels:
        - __name__
      regex: kong_(.*)_latency_ms_(bucket|count|sum)
      target_label: __name__
      replacement: kong_latency_$2

    - action: replace
      source_labels:
        - __name__
        - direction
      regex: (kong_bandwidth_bytes);(egress|ingress)
      separator: ;
      target_label: type
      replacement: $2
    - action: replace
      source_labels:
        - __name__
      regex: kong_bandwidth_bytes
      target_label: __name__
      replacement: kong_bandwidth

    - action: replace
      source_labels:
        - __name__
      regex: kong_nginx_connections_total
      target_label: node_id
      replacement: ""
    - action: replace
      source_labels:
        - __name__
      regex: kong_nginx_connections_total
      target_label: subsystem
      replacement: ""
    - action: replace
      source_labels:
        - __name__
      regex: kong_nginx_connections_total
      target_label: __name__
      replacement: kong_nginx_http_current_connections
Thank you for your feedback.
Was this page useful?
Too much on your plate? close cta icon
More features, less infrastructure with Kong Konnect. 1M requests per month for free.
Try it for Free
  • Kong
    THE CLOUD CONNECTIVITY COMPANY

    Kong powers reliable digital connections across APIs, hybrid and multi-cloud environments.

    • Company
    • Customers
    • Events
    • Investors
    • Careers Hiring!
    • Partners
    • Press
    • Contact
  • Products
    • Kong Konnect
    • Kong Gateway
    • Kong Mesh
    • Get Started
    • Pricing
  • Resources
    • eBooks
    • Webinars
    • Briefs
    • Blog
    • API Gateway
    • Microservices
  • Open Source
    • Install Kong Gateway
    • Kong Community
    • Kubernetes Ingress
    • Kuma
    • Insomnia
  • Solutions
    • Decentralize
    • Secure & Govern
    • Create a Dev Platform
    • API Gateway
    • Kubernetes
    • Service Mesh
Star
  • Terms•Privacy
© Kong Inc. 2023