Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[DOCU-3215] 3.3 upgrade guide #5590

Merged
merged 6 commits into from
May 18, 2023
Merged

[DOCU-3215] 3.3 upgrade guide #5590

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
20f05fc
Add upgrade table for 3.3
cloudjumpercat May 12, 2023
86b7754
Fix rolling upgrades column for 3.1.x releases
cloudjumpercat May 12, 2023
6074c83
Add info about plugin queue breaking changes to upgrade doc
cloudjumpercat May 15, 2023
450c85f
Add traditional_compat and Plugins to breaking changes section
cloudjumpercat May 15, 2023
f770b43
Fix changelog link
cloudjumpercat May 17, 2023
70cfaf2
Apply suggestions from code review
cloudjumpercat May 18, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 48 additions & 3 deletions app/_src/gateway/upgrade-v2.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,8 +29,7 @@ upgrade to 2.8.2, [then migrate to {{page.kong_version}}](#migrate-db).
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)](https://github.com/Kong/kong/blob/release/3.2.x/CHANGELOG.md#310) and
[Enterprise](/gateway/changelog/#3210) Gateway changelogs. Since {{site.base_gateway}}
[open-source (OSS) and Enterprise Gateway changelogs](/gateway/changelog/). Since {{site.base_gateway}}
is built on an open-source foundation, any breaking changes in OSS affect all {{site.base_gateway}} packages.

{{site.base_gateway}} does not support directly upgrading from 1.x to {{page.kong_version}}.
Expand Down Expand Up @@ -60,7 +59,7 @@ The following table outlines various upgrade path scenarios to {{page.kong_versi

{% endif_version %}

{% if_version gte: 3.2.x %}
{% if_version eq: 3.2.x %}

| **Current version** | **Topology** | **Direct upgrade possible?** | **Upgrade path** |
| ------------------- | ------------ | ---------------------------- | ---------------- |
Expand All @@ -80,6 +79,29 @@ The following table outlines various upgrade path scenarios to {{page.kong_versi

{% endif_version %}

{% if_version eq: 3.3.x %}
cloudjumpercat marked this conversation as resolved.
Show resolved Hide resolved

| **Current version** | **Topology** | **Direct upgrade possible?** | **Upgrade path** |
| ------------------- | ------------ | ---------------------------- | ---------------- |
| 2.x–2.7.x | Traditional | No | [Upgrade to 2.8.2.x](/gateway/2.8.x/install-and-run/upgrade-enterprise/) (required for blue/green deployments only), [upgrade to 3.0.x](/gateway/3.0.x/upgrade/), [upgrade to 3.1.x](/gateway/3.1.x/upgrade/#migrate-db), [upgrade to 3.2.x](#migrate-db), and then [upgrade to 3.3.x](#migrate-db). |
| 2.x–2.7.x | Hybrid | No | [Upgrade to 2.8.2.x](/gateway/2.8.x/install-and-run/upgrade-enterprise/), [upgrade to 3.0.x](/gateway/3.0.x/upgrade/), [upgrade to 3.1.x](/gateway/3.1.x/upgrade/#migrate-db), [upgrade to 3.2.x](#migrate-db), and then [upgrade to 3.3.x](#migrate-db). |
| 2.x–2.7.x | DB less | No | [Upgrade to 3.0.x](/gateway/3.0.x/upgrade/), [upgrade to 3.1.x](/gateway/3.1.x/upgrade/#migrate-db), [upgrade to 3.2.x](#migrate-db), and then [upgrade to 3.3.x](#migrate-db). |
| 2.8.x | Traditional | No | [Upgrade to 3.1.1.3](/gateway/3.1.x/upgrade/#migrate-db), [upgrade to 3.2.x](#migrate-db), and then [upgrade to 3.3.x](#migrate-db). |
| 2.8.x | Hybrid | No | [Upgrade to 3.1.1.3](/gateway/3.1.x/upgrade/#migrate-db), [upgrade to 3.2.x](#migrate-db), and then [upgrade to 3.3.x](#migrate-db). |
| 2.8.x | DB less | No | [Upgrade to 3.1.1.3](/gateway/3.1.x/upgrade/#migrate-db), [upgrade to 3.2.x](#migrate-db), and then [upgrade to 3.3.x](#migrate-db). |
| 3.0.x | Traditional | No | [Upgrade to 3.1.x](/gateway/3.1.x/upgrade/#migrate-db), [upgrade to 3.2.x](#migrate-db), and then [upgrade to 3.3.x](#migrate-db). |
| 3.0.x | Hybrid | No | [Upgrade to 3.1.x](/gateway/3.1.x/upgrade/#migrate-db), [upgrade to 3.2.x](#migrate-db), and then [upgrade to 3.3.x](#migrate-db). |
| 3.0.x | DB less | No | [Upgrade to 3.1.x](/gateway/3.1.x/upgrade/#migrate-db), [upgrade to 3.2.x](#migrate-db), and then [upgrade to 3.3.x](#migrate-db). |
| 3.1.x | Traditional | No | [Upgrade to 3.2.x](#migrate-db), and then [upgrade to 3.3.x](#migrate-db). |
| 3.1.0.x-3.1.1.2 | Hybrid | No | [Upgrade to 3.1.1.3](/gateway/3.1.x/upgrade/#migrate-db), [upgrade to 3.2.x](#migrate-db), and then [upgrade to 3.3.x](#migrate-db). |
| 3.1.1.3 | Hybrid | No | [Upgrade to 3.2.x](#migrate-db), and then [upgrade to 3.3.x](#migrate-db). |
| 3.1.x | DB less | No | [Upgrade to 3.2.x](#migrate-db), and then [upgrade to 3.3.x](#migrate-db). |
| 3.2.x | Traditional | Yes | [Upgrade to 3.3.x](#migrate-db). |
| 3.2.x | Hybrid | Yes | [Upgrade to 3.3.x](#migrate-db). |
| 3.2.x | DB less | Yes | [Upgrade to 3.3.x](#migrate-db). |
cloudjumpercat marked this conversation as resolved.
Show resolved Hide resolved

{% endif_version %}

## Upgrade considerations and breaking changes

Before upgrading, review any configuration or breaking changes in this version and prior versions that
Expand All @@ -88,6 +110,29 @@ 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.

### Plugins

For breaking changes to plugins, see the [Kong Gateway Changelog](/gateway/changelog/) for your {{site.base_gateway}} version.

{% if_version gte:3.3.x %}
### Plugin queuing

The plugin queuing system was reworked in {{site.base_gateway}} 3.3.x, so some plugin parameters may not function as expected anymore. If you use queues in the following plugins, new parameters must be configured:

* [HTTP Log](/hub/kong-inc/http-log/)
* [OpenTelemetry](/hub/kong-inc/opentelemetry/)
* [Datadog](/hub/kong-inc/datadog/)
* [StatsD](/hub/kong-inc/statsd/)
* [Zipkin](/hub/kong-inc/zipkin/)

For more information about how plugin queuing works and the plugin queuing parameters you can configure, see [About Plugin Queuing](/gateway/{{page.kong_version}}/kong-plugins/queue/) and [Plugin Queuing Reference](/gateway/{{page.kong_version}}/kong-plugins/queue/reference/).

### Traditional compatibility router

The `traditional_compat` router mode has been made more compatible with the behavior of `traditional` mode by splitting routes with multiple paths into multiple `atc` routes with separate priorities. Since the introduction of the new router in {{site.base_gateway}} 3.0, `traditional_compat` mode assigned only one priority to each route, even if different prefix path lengths and regular expressions were mixed in a route. This was not how multiple paths were handled in the `traditional` router and the behavior has now been changed so that a separate priority value is assigned to each path in a route.

{% endif_version %}

{% if_version gte:3.2.x %}

### PostgreSQL SSL version bump
Expand Down