Skip to content

Commit 379d307

Browse files
kikitokikito
committed
docs(upgrade) add 2.3.0 upgrade path
1 parent 1d2c517 commit 379d307

File tree

1 file changed

+152
-0
lines changed

1 file changed

+152
-0
lines changed

‎UPGRADE.md

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,158 @@ starts new workers, which take over from old workers before those old workers
3636
are terminated. In this way, Kong will serve new requests via the new
3737
configuration, without dropping existing in-flight connections.
3838

39+
## Upgrade to `2.3.0`
40+
41+
Kong adheres to [semantic versioning](https://semver.org/), which makes a
42+
distinction between "major", "minor", and "patch" versions. The upgrade path
43+
will be different depending on which previous version from which you are migrating.
44+
45+
If you are migrating from 2.0.0, 2.1.x, or 2.2.x upgrading into 2.3.x is a minor upgrade,
46+
but read below for important instructions on database migration, especially
47+
for Cassandra users.
48+
49+
If you are migrating from 1.x, upgrading into 2.3.x is a major upgrade,
50+
so, in addition, be aware of any [breaking changes](#breaking-changes-2.0.0)
51+
between the 1.x and 2.x series below, further detailed in the
52+
[CHANGELOG.md](https://github.com/Kong/kong/blob/2.0.0/CHANGELOG.md) document.
53+
54+
55+
#### 1. Dependencies
56+
57+
If you are using the provided binary packages, all necessary dependencies
58+
for the gateway are bundled and you can skip this section.
59+
60+
If you are building your dependencies by hand, there are changes since the
61+
previous release, so you will need to rebuild them with the latest patches.
62+
63+
The required OpenResty version for kong 2.3.x is
64+
[1.17.8.2](https://openresty.org/en/changelog-1017008.html). This is more recent
65+
than the version in Kong 2.1.0 (which used `1.15.8.3`). In addition to an upgraded
66+
OpenResty, you will need the correct [OpenResty
67+
patches](https://github.com/Kong/kong-build-tools/tree/master/openresty-build-tools/openresty-patches)
68+
for this new version, including the latest release of
69+
[lua-kong-nginx-module](https://github.com/Kong/lua-kong-nginx-module).
70+
The [kong-build-tools](https://github.com/Kong/kong-build-tools)
71+
repository contains [openresty-build-tools](https://github.com/Kong/kong-build-tools/tree/master/openresty-build-tools),
72+
which allows you to build OpenResty with the necessary patches
73+
and modules easily.
74+
75+
There is a new way to deploy Go using Plugin Servers. You can read more about it the [Go section of the docs](https://docs.konghq.com/2.3.x/go).
76+
77+
#### 2. Template Changes
78+
79+
There are **Changes in the Nginx configuration file**, between kong 2.0.0,
80+
2.1.0, 2.2.0 and 2.3.0.
81+
82+
To view the configuration changes between versions, clone the
83+
[Kong repository](https://github.com/kong/kong) and run `git diff`
84+
on the configuration templates, using `-w` for greater readability.
85+
86+
Here's how to see the differences between 2.0.0 and 2.3.0:
87+
88+
```
89+
git clone https://github.com/kong/kong
90+
cd kong
91+
git diff -w 2.0.0 2.3.0 kong/templates/nginx_kong*.lua
92+
```
93+
94+
To produce a patch file, use the following command:
95+
96+
```
97+
git diff 2.0.0 2.3.0 kong/templates/nginx_kong*.lua > kong_config_changes.diff
98+
```
99+
100+
#### 3. Suggested Upgrade Path
101+
102+
##### Upgrade from `0.x` to `2.3.0`
103+
104+
The lowest version that Kong 2.3.0 supports migrating from is 1.0.0.
105+
If you are migrating from a version lower than 0.14.1, you need to
106+
migrate to 0.14.1 first. Then, once you are migrating from 0.14.1,
107+
please migrate to 1.5.0 first.
108+
109+
The steps for upgrading from 0.14.1 to 1.5.0 are the same as upgrading
110+
from 0.14.1 to Kong 1.0. Please follow the steps described in the
111+
"Migration Steps from 0.14" in the [Suggested Upgrade Path for Kong
112+
1.0](#kong-1-0-upgrade-path), with the addition of the `kong
113+
migrations migrate-apis` command, which you can use to migrate legacy
114+
`apis` configurations.
115+
116+
Once you migrated to 1.5.0, you can follow the instructions in the section
117+
below to migrate to 2.3.0.
118+
119+
##### Upgrade from `1.0.0` - `2.2.0` to `2.3.0`
120+
121+
**Postgres**
122+
123+
Kong 2.3.0 supports a no-downtime migration model. This means that while the
124+
migration is ongoing, you will have two Kong clusters running, sharing the
125+
same database. (This is sometimes called the Blue/Green migration model.)
126+
127+
The migrations are designed so that the new version of Kong is able to use
128+
the database as it is migrated while the old Kong cluster keeps working until
129+
it is time to decommission it. For this reason, the migration is split into
130+
two steps, performed via commands `kong migrations up` (which does
131+
only non-destructive operations) and `kong migrations finish` (which puts the
132+
database in the final expected state for Kong 2.3.0).
133+
134+
1. Download 2.3.0, and configure it to point to the same datastore
135+
as your old (1.0 to 2.0) cluster. Run `kong migrations up`.
136+
2. Once that finishes running, both the old (pre-2.1) and new (2.3.0)
137+
clusters can now run simultaneously. Start provisioning 2.3.0 nodes,
138+
but do not use their Admin API yet. If you need to perform Admin API
139+
requests, these should be made to the old cluster's nodes. The reason
140+
is to prevent the new cluster from generating data that is not understood
141+
by the old cluster.
142+
3. Gradually divert traffic away from your old nodes, and into
143+
your 2.3.0 cluster. Monitor your traffic to make sure everything
144+
is going smoothly.
145+
4. When your traffic is fully migrated to the 2.3.0 cluster,
146+
decommission your old nodes.
147+
5. From your 2.3.0 cluster, run: `kong migrations finish`.
148+
From this point on, it will not be possible to start
149+
nodes in the old cluster pointing to the same datastore anymore. Only run
150+
this command when you are confident that your migration
151+
was successful. From now on, you can safely make Admin API
152+
requests to your 2.3.0 nodes.
153+
154+
**Cassandra**
155+
156+
Due to internal changes, the table schemas used by Kong 2.3.0 on Cassandra
157+
are incompatible with those used by Kong 2.0.0. Migrating using the usual commands
158+
`kong migrations up` and `kong migrations finish` will require a small
159+
window of downtime, since the old and new versions cannot use the
160+
database at the same time. Alternatively, to keep your previous version fully
161+
operational while the new one initializes, you will need to transfer the
162+
data to a new keyspace via a database dump, as described below:
163+
164+
1. Download 2.3.0, and configure it to point to a new keyspace.
165+
Run `kong migrations bootstrap`.
166+
2. Once that finishes running, both the old (pre-2.1) and new (2.3.0)
167+
clusters can now run simultaneously, but the new cluster does not
168+
have any data yet.
169+
3. On the old cluster, run `kong config db_export`. This will create
170+
a file `kong.yml` with a database dump.
171+
4. Transfer the file to the new cluster and run
172+
`kong config db_import kong.yml`. This will load the data into the new cluster.
173+
5. Gradually divert traffic away from your old nodes, and into
174+
your 2.3.0 cluster. Monitor your traffic to make sure everything
175+
is going smoothly.
176+
6. When your traffic is fully migrated to the 2.3.0 cluster,
177+
decommission your old nodes.
178+
179+
##### Installing 2.3.0 on a Fresh Datastore
180+
181+
The following commands should be used to prepare a new 2.3.0 cluster from a
182+
fresh datastore. By default the `kong` CLI tool will load the configuration
183+
from `/etc/kong/kong.conf`, but you can optionally use the flag `-c` to
184+
indicate the path to your configuration file:
185+
186+
```
187+
$ kong migrations bootstrap [-c /path/to/your/kong.conf]
188+
$ kong start [-c /path/to/your/kong.conf]
189+
```
190+
39191
## Upgrade to `2.2.0`
40192

41193
Kong adheres to [semantic versioning](https://semver.org/), which makes a

0 commit comments

Comments
 (0)