Skip to content
Kong Logo | Kong Docs Logo
search
  • We're Hiring!
  • Docs
    • Kong Gateway
    • Kong Konnect
    • Kong Mesh
    • Plugin Hub
    • decK
    • Kubernetes Ingress Controller
    • Insomnia
    • Kuma

    • Docs contribution guidelines
  • Plugin Hub
  • Support
  • Community
  • Kong Academy
Get a Demo Start Free Trial
  • Kong Gateway
  • Kong Konnect
  • Kong Mesh
  • Plugin Hub
  • decK
  • Kubernetes Ingress Controller
  • Insomnia
  • Kuma

  • Docs contribution guidelines
  • 3.2.x (latest)
  • 3.1.x
  • 3.0.x
  • 2.8.x
  • 2.7.x
  • 2.6.x
  • Older Enterprise versions (2.1-2.5)
  • Older OSS versions (2.1-2.5)
  • Archive (pre-2.1)
    • Overview of Kong Gateway
      • Version Support Policy
      • Third Party Dependencies
      • Browser Support
    • Stability
    • Release Notes
      • Services
        • Overview
        • Configure Routes with Expressions
      • Upstreams
      • Plugins
      • Routing Traffic
      • Load Balancing
      • Health Checks and Circuit Breakers
      • Kong Performance Testing
    • Glossary
    • Get Kong
    • Services and Routes
    • Rate Limiting
    • Proxy Caching
    • Key Authentication
    • Load-Balancing
      • Overview
        • Overview
        • Deploy Kong Gateway in Hybrid mode
      • DB-less Deployment
      • Traditional
      • Overview
        • Helm
        • OpenShift with Helm
        • kubectl apply
        • Kubernetes Deployment Options
        • Using docker run
        • Build your own Docker images
        • Amazon Linux
        • Debian
        • Red Hat
        • Ubuntu
      • Running Kong as a non-root user
      • Securing the Admin API
      • Using systemd
      • Start Kong Gateway Securely
      • Programatically Creating Admins
      • Enabling RBAC
      • Overview
      • Download your License
      • Deploy Enterprise License
      • Using the License API
      • Monitor Licenses Usage
      • Default Ports
      • DNS Considerations
      • Network and Firewall
      • CP/DP Communication through a Forward Proxy
        • Configure PostgreSQL TLS
        • Troubleshooting PostgreSQL TLS
    • Kong Configuration File
    • Environment Variables
    • Serving a Website and APIs from Kong
      • Overview
      • Prometheus
      • StatsD
      • Datadog
      • Overview
      • Writing a Custom Trace Exporter
      • Tracing API Reference
    • Resource Sizing Guidelines
    • Security Update Process
    • Blue-Green Deployments
    • Canary Deployments
    • Clustering Reference
      • Log Reference
      • Dynamic log level updates
      • Customize Gateway Logs
      • Upgrade Kong Gateway 3.x.x
      • Migrate from OSS to Enterprise
    • Overview
      • Overview
      • Metrics
      • Analytics with InfluxDB
      • Analytics with Prometheus
      • Estimate Analytics Storage in PostgreSQL
      • Overview
      • Getting Started
      • Advanced Usage
        • Overview
        • Environment Variables
        • AWS Secrets Manager
        • Google Secrets Manager
        • Hashicorp Vault
        • Securing the Database with AWS Secrets Manager
      • Reference Format
      • Overview
      • Get Started with Dynamic Plugin Ordering
      • Overview
      • Enable the Dev Portal
      • Publish an OpenAPI Spec
      • Structure and File Types
      • Themes Files
      • Working with Templates
      • Using the Editor
        • Basic Auth
        • Key Auth
        • OIDC
        • Sessions
        • Adding Custom Registration Fields
        • Manage Developers
        • Developer Roles and Content Permissions
        • 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
        • 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
      • SMTP
      • Workspaces
      • Helpers CLI
      • Portal API Documentation
    • Audit Logging
    • Keyring and Data Encryption
    • Workspaces
    • Consumer Groups
    • Event Hooks
    • Configure Data Plane Resilience
    • About Control Plane Outage Management
      • Overview
      • Install the FIPS Compliant Package
      • FIPS 140-2 Compliant Plugins
    • Overview
    • Enable Kong Manager
      • Services and Routes
      • Rate Limiting
      • Proxy Caching
      • Authentication with Consumers
      • Load Balancing
      • Overview
      • Create a Super Admin
      • Workspaces and Teams
      • Reset Passwords and RBAC Tokens
      • Basic Auth
        • Configure LDAP
        • LDAP Service Directory Mapping
        • Configure OIDC
        • OIDC Authenticated Group Mapping
      • Sessions
        • Overview
        • Enable RBAC
        • Add a Role and Permissions
        • Create a User
        • Create an Admin
    • Networking Configuration
    • Workspaces
    • Create Consumer Groups
    • Sending Email
    • Overview
    • File Structure
    • Implementing Custom Logic
    • Plugin Configuration
    • Accessing the Data Store
    • Storing Custom Entities
    • Caching Custom Entities
    • Extending the Admin API
    • Writing Tests
    • (un)Installing your Plugin
      • Overview
      • kong.client
      • kong.client.tls
      • kong.cluster
      • kong.ctx
      • kong.ip
      • kong.jwe
      • kong.log
      • kong.nginx
      • kong.node
      • kong.request
      • kong.response
      • kong.router
      • kong.service
      • kong.service.request
      • kong.service.response
      • kong.table
      • kong.tracing
      • kong.vault
      • kong.websocket.client
      • kong.websocket.upstream
      • Go
      • Javascript
      • Python
      • Running Plugins in Containers
      • External Plugin Performance
    • Overview
        • Overview
        • 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
      • Authentication Reference
      • Allow Multiple Authentication Plugins
    • Rate Limiting Plugin
      • Add a Body Value
    • GraphQL
      • gRPC Plugins
      • Configure a gRPC service
    • Overview
    • Information Routes
    • Health Routes
    • Tags
    • Debug Routes
    • Services
    • Routes
    • Consumers
    • Plugins
    • Certificates
    • CA Certificates
    • SNIs
    • Upstreams
    • Targets
    • Vaults
    • Keys
    • Licenses
    • Workspaces
    • RBAC
    • Admins
    • Developers
    • Consumer Groups
    • Event Hooks
    • Keyring and Data Encryption
    • Audit Logs
    • kong.conf
    • Injecting Nginx Directives
    • CLI
    • Key Management
    • Performance Testing Framework
    • Router Expressions Language
    • FAQ

github-edit-pageEdit this page

report-issueReport an issue

enterprise-switcher-iconSwitch to OSS

On this page
  • Upgrade path for Kong Gateway releases
  • Upgrade path for Kong Gateway 3.2.x
  • Upgrade considerations and breaking changes
    • PostgreSQL SSL version bump
    • Changes to the Kong-Debug header
    • JWT plugin
    • Session library upgrade
    • Kong for Kubernetes considerations
    • Hybrid mode considerations
    • Template changes
  • General upgrade path
    • Traditional mode
    • Hybrid mode
  • Upgrade to Kong Gateway 3.x.x and retain 2.x.x alerts for Prometheus
Kong Gateway
3.2.x (latest)
  • Home
  • Kong Gateway
  • Upgrade Kong Gateway 3.x.x

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.2.x is a minor upgrade. The lowest version that Kong 3.2.x supports migrating from directly is 3.0.x.

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.2.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.2.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.2.x from there.

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

Upgrade path for Kong Gateway 3.2.x

The following table outlines various upgrade path scenarios to 3.2.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, and then upgrade to 3.2.x.
2.x–2.7.x Hybrid No Upgrade to 2.8.2.x, upgrade to 3.0.x, upgrade to 3.1.x, and then upgrade to 3.2.x.
2.x–2.7.x DB less No Upgrade to 3.0.x, upgrade to 3.1.x, and then upgrade to 3.2.x.
2.8.x Traditional No Upgrade to 3.1.1.3, and then upgrade to 3.2.x.
2.8.x Hybrid No Upgrade to 3.1.1.3, and then upgrade to 3.2.x.
2.8.x DB less No Upgrade to 3.1.1.3, and then upgrade to 3.2.x.
3.0.x Traditional No Upgrade to 3.1.x, and then upgrade to 3.2.x.
3.0.x Hybrid No Upgrade to 3.1.x, and then upgrade to 3.2.x.
3.0.x DB less No Upgrade to 3.1.x, and then upgrade to 3.2.x.
3.1.x Traditional Yes Upgrade to 3.2.x.
3.1.0.x-3.1.1.2 Hybrid No Upgrade to 3.1.1.3, and then upgrade to 3.2.x.
3.1.1.3 Hybrid Yes Upgrade to 3.2.x.
3.1.x DB less Yes Upgrade to 3.2.x.

Upgrade considerations and breaking changes

Before upgrading, review any configuration or breaking changes in this version and prior versions that affect your current installation.

You may need to adopt different upgrade paths depending on your deployment methods, set of features in use, custom plugins, for example.

PostgreSQL SSL version bump

The default PostgreSQL SSL version has been bumped to TLS 1.2.

This causes changes to pg_ssl_version (set through kong.conf):

  • The default value is now tlsv1_2.
  • pg_ssl_version previously accepted any string. In this version, it requires one of the following values: tlsv1_1, tlsv1_2, tlsv1_3 or any.

This mirrors the setting ssl_min_protocol_version in PostgreSQL 12.x and onward. See the PostgreSQL documentation for more information about that parameter.

To use the default setting in kong.conf, verify that your Postgres server supports TLS 1.2 or higher versions, or set the TLS version yourself.

TLS versions lower than tlsv1_2 are already deprecated and are considered insecure from PostgreSQL 12.x onward.

Changes to the Kong-Debug header

Added the allow_debug_header configuration property to kong.conf to constrain the Kong-Debug header for debugging. This option defaults to off.

If you were previously relying on the Kong-Debug header to provide debugging information, set allow_debug_header: on in kong.conf to continue doing so.

JWT plugin

The JWT plugin now denies any request that has different tokens in the JWT token search locations.

Session library upgrade

The lua-resty-session library has been upgraded to v4.0.0. This version includes a full rewrite of the session library.

This upgrade affects the following:

  • Session plugin
  • OpenID Connect plugin
  • SAML plugin
  • Any session configuration that uses the Session or OpenID Connect plugin in the background, including sessions for Kong Manager and Dev Portal.

All existing sessions are invalidated when upgrading to this version. For sessions to work as expected in this version, all nodes must run Kong Gateway 3.2.x or later. If multiple data planes run different versions, every time a user hits a different DP, even for the same endpoint, the previous session is invalidated.

For that reason, we recommend that during upgrades, proxy nodes with mixed versions run for as little time as possible. During that time, the invalid sessions could cause failures and partial downtime.

You can expect the following behavior:

  • After upgrading the control plane: Existing Kong Manager and Dev Portal sessions will be invalidated and all users will be required to log back in.
  • After upgrading the data planes: Existing proxy sessions will be invalidated. If you have an IdP configured, users will be required to log back into the IdP.

Session configuration parameter changes

The session library upgrade includes new, changed, and removed parameters. Here’s how they function:

  • The new parameter idling_timeout, which replaces cookie_lifetime, has a default value of 900. Unless configured differently, sessions expire after 900 seconds (15 minutes) of idling.
  • The new parameter absolute_timeout has a default value of 86400. Unless configured differently, sessions expire after 86400 seconds (24 hours).
  • All renamed parameters will still work by their old names.
  • Any removed parameters will not work anymore. They won’t break your configuration, and sessions will continue to function, but they will not contribute anything to the configuration.

Existing session configurations will still work as configured with the old parameters.

Do not change any parameters to the new ones until all CP and DP nodes are upgraded.

After you have upgraded all of your CP and DP nodes to 3.2 and ensured that your environment is stable, we recommend updating parameters to their new renamed versions, and cleaning out any removed parameters from session configuration to avoid unpredictable behavior.

Session plugin

Old parameter name New parameter name
cookie_lifetime rolling_timeout
cookie_idletime idling_timeout
cookie_samesite cookie_same_site
cookie_httponly cookie_http_only
cookie_discard stale_ttl
cookie_renew Removed, no replacement parameter.

SAML plugin

Old parameter name New parameter name
session_cookie_lifetime session_rolling_timeout
session_cookie_idletime session_idling_timeout
session_cookie_samesite session_cookie_same_site
session_cookie_httponly session_cookie_http_only
session_memcache_prefix session_memcached_prefix
session_memcache_socket session_memcached_socket
session_memcache_host session_memcached_host
session_memcache_port session_memcached_port
session_redis_cluster_maxredirections session_redis_cluster_max_redirections
session_cookie_renew Removed, no replacement parameter.
session_cookie_maxsize Removed, no replacement parameter.
session_strategy Removed, no replacement parameter.
session_compressor Removed, no replacement parameter.

OpenID Connect plugin

Old parameter name New parameter name
authorization_cookie_lifetime authorization_rolling_timeout
authorization_cookie_samesite authorization_cookie_same_site
authorization_cookie_httponly authorization_cookie_http_only
session_cookie_lifetime session_rolling_timeout
session_cookie_idletime session_idling_timeout
session_cookie_samesite session_cookie_same_site
session_cookie_httponly session_cookie_http_only
session_memcache_prefix session_memcached_prefix
session_memcache_socket session_memcached_socket
session_memcache_host session_memcached_host
session_memcache_port session_memcached_port
session_redis_cluster_maxredirections session_redis_cluster_max_redirections
session_cookie_renew Removed, no replacement parameter.
session_cookie_maxsize Removed, no replacement parameter.
session_strategy Removed, no replacement parameter.
session_compressor Removed, no replacement parameter.

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 Gateway version back, check the upgrade path recommendations.

Although not required, users should upgrade their chart version and Kong Gateway 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 Gateway.

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 Gateway release in the Kong Gateway cluster, and runs both migrations up and migrations finish jobs.

If you split your Kong Gateway 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 Gateway package before running kong migrations finish.

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 the previous version 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 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.
  • The Rate Limiting Advanced plugin does not support the cluster strategy in hybrid mode. The redis strategy must be used instead.

Template changes

There are changes in the Nginx configuration file between every minor and major version of Kong Gateway starting with 2.0.x.

In 3.0.x, the deprecated alias of Kong.serve_admin_api was removed. If your custom Nginx templates still use it, change it to Kong.admin_content.

OSS
Enterprise

To view all of the configuration changes between versions, clone the Kong repository and run git diff on the configuration templates, using -w for greater readability.

Here’s how to see the differences between previous versions and 3.2.2:

git clone https://github.com/kong/kong
cd kong
git diff -w 2.0.0 3.2.2 kong/templates/nginx_kong*.lua

Adjust the starting version number (2.0.0 in the example) to the version number you are currently using.

To produce a patch file, use the following command:

git diff 2.0.0 3.2.2 kong/templates/nginx_kong*.lua > kong_config_changes.diff

Adjust the starting version number to the version number (2.0.0 in the example) you are currently using.

The default template for Kong Gateway can be found using this command on the system running your Kong Gateway instance: find / -type d -name "templates" | grep kong.

When upgrading, make sure to run this command on both the old and new clusters, diff the files to identify any changes, and apply them as needed.

General upgrade path

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

Depending on the database you’re using (Postgres or Cassandra), 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?
  • 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