Migration Notes

This page describes instructions and important applicative changes when updating the Distribution Service from one version to another, if any.

v3.0.x to v3.5.x

The context path of the Distribution Service has been changed from /v3/ to /v3_5 to allow concurrent use of the new v3.5 T1C along with legacy v3 T1C instances, as well as new endpoints for the central agent registry for shared environments. This require the gateway to be bootstrapped again to add the new routes.

If you intend to host both v3 and v3.5 versions of the DS at the same time, it is important to select a different service name in the DS gateway bootstrapping request.

v3.5.0 to v3.5.1

New routes

New secure routes have been added to the Kong gateway for the central dynamic CORS configuration API. This requires a new execution of the gateway bootstrapping. If you had previously upgraded to v3.5.0 from v3.0.x, this step must be executed again.

Central CORS configuration

In order to better secure the DS and consuming applications, the DS now has a dynamic CORS policy analogous to the T1C. It is enabled by default and unconfigured, all origins are allowed. So it is important to note that you must configure the DS to only allow the origins required for your web applications.

The DS CORS configuration, when enabled and when the allowed origins list is non empty, also overrides the versioned context configuration, making it so that if the CORS allowed origins need to be updated, it only needs to be done once and not for every version currently in use.

Implicit Version Creation

In order to reduce the overhead when releasing a new version, it is now possible to enable implicit version creation. It is disabled by default, but when enabled a new version is created implicitly when a device registers with the DS with a unknown version. When implicitly creating a new version, the DS does the following:

• It creates the version metadata with a new registration API key

• If a template string is configured with the necessary variable values, internal download URI's are generated from the template for every supported package OS

• The latest context, SSL and file digest configurations are duplicated for the new version.

Important: if enabled and an unknown version registers with a higher version than the latest, this implicit version becomes the latest version and will be the version that is presented for download. It is therefore very important that all the installer packages are available at the configured template URI, otherwise the installer download will fail.