[guide] Upgrade Path

[subnetmarco]

Explain what is the recommended upgrade path to update to newer versions of Kong.

[Rylon]

Thanks @thefosk, unfortunately due to historical reasons, our current platform is a little manual when it comes to provisioning new servers, so this limitation makes the upgrade path needlessly painful for us and difficult to automate (we're using Ansible).

If we were using something like EC2 then it would be a lot easier, but I think in-place upgrades should be considered to support all implementations, and to fit into the standard package/template/service pattern you see with most configuration management systems.

[Rylon]

For the full picture, this is the error currently returned if you try to do an in-place upgrade and then restart the service, for example this was going from 0.3.2 to 0.4.0:

stdout:  * Restarting API management layer kong
stderr: nginx: [emerg] BIO_new_file("/usr/local/lib/luarocks/rocks/kong/0.3.2-1/ssl/kong-default.crt") failed (SSL: error:02001002:system library:fopen:No such file or directory:fopen('/usr/local/lib/luarocks/rocks/kong/0.3.2-1/ssl/kong-default.crt','r') error:2006D080:BIO routines:BIO_new_file:no such file)

[subnetmarco]

@Rylon thanks for the error log, I know what the problem is. Let me see if I can push a patch to fix this problem in the future.

[subnetmarco]

@Rylon Can you please tell me the result of:

$ ls /usr/local/lib/luarocks/rocks/kong

And also the output of:

$ kong version

[Rylon]

Thanks @thefosk !

I completed a manual upgrade to 0.4.1 recently, so this is the current output:

$ ls /usr/local/lib/luarocks/rocks/kong
0.4.1-1
$ kong version
Kong version: 0.4.1

The error above was when we tried to do an in-place upgrade from 0.3.2 to 0.4.0. Of course the package upgrade works fine, but then you are no longer able to stop or restart the service, because the older 0.3.2 files are missing.

Hope that helps! Thanks

[thibaultcha]

I did that in 0.5.4: https://github.com/Mashape/kong/blob/master/UPGRADE.md#suggested-upgrade-path

Close?

[Rylon]

@thibaultCha that looks great, thanks! One clarification, where you say this:

"If you see the "Schema up to date" message, you only have to reload Kong"

Are there any other messages that may require more than a reload?

Thanks!

[thibaultcha]

@Rylon Hmmmm nope; in fact, I don't see any other message that could be returned by kong migrations, except an error maybe, which would be more problematic. A reload is as good as a restart (without downtime), except that it won't restart third-party services (like dnsmasq which runs alongside Kong). But that is totally fine since only Kong generally gets an update.

If the migration between 2 versions requires additional steps or other commands, they will be described in their own section in UPGRADE.md.

[Rylon]

@thibaultCha that's great then, thanks for the clarification. :+1: