Document updated on Mar 11, 2024
Upgrading KrakenD from an older version
Upgrading to a new version of KrakenD is designed to be straightforward, thanks to our commitment to maintaining backward compatibility across versions within the same major release (e.g., within 2.x
versions). You can generally update KrakenD to a newer version without altering your configuration. However, to ensure optimal performance and access to the latest features, reviewing and adjusting your configuration is wise.
Upgrade steps
- Review the changelog. This document provides a chronological list of releases detailing new features, bug fixes, and possible breaking changes between major versions.
- Adjust your configuration and run the linter as needed. Below, you’ll find the changes between versions. Scroll down to your current version and apply all changes above it. Then, run the linter (
krakend check --lint
), which is designed to scrutinize your configuration rigorously. - Update the KrakenD binary. Replace the existing binary file with the latest version. This process varies depending on how KrakenD was installed and whether it is container-based or not.
The list below is automatically generated based on the changelog.
Upgrade to CE v2.8 (latest)
Configuration changes needed to upgrade to v2.8:
- The
letgoapp/influx
namespace, which was available for historical reasons, has been removed from the configuration schema. Rename it totelemetry/influx
for a quick fix (which is also deprecated), or upgrade to OpenTelemetry for a long-term solution.
Upgrade to CE v2.7
Configuration changes needed to upgrade to v2.7:
- The properties
public_key
andprivate_key
of thetls
configuration have been moved under an arraykeys
to facilitate multiple certificates and domains. Read more
Upgrade to CE v2.6
Configuration changes needed to upgrade to v2.6:
- Removed from schema previosuly deprecated fields
allow_insecure_connections
in the root. Must be declared underclient_tls.allow_insecure_connections
now. - Removed from schema previously deprecated
prefetch_size
andprefetch_count
attributes from AMQP. These attributes did not have any effect in the software. - The telemetry exporters based in
telemetry/opencensus
, although they are still available, won’t receive further updates and will be deprecated in the future. All efforts are focused on OpenTelemetry instead. - The telemetry exporter
telemetry/influx
is still available, but won’t receive further updates and will be deprecated in the future. All efforts are focused on OpenTelemetry instead.
Upgrade to CE v2.5
Configuration changes needed to upgrade to v2.5:
- The flag
router.use_h2c
has moved to the root level asuse_h2c
, and its usage inside therouter
is marked as deprecated.
Upgrade to CE v2.4
Configuration changes needed to upgrade to v2.4:
- The flag
allow_insecure_connections
was relocated underclient_tls
in v2.3 and the old location ontls
is no longer supported. - The flag
prefer_server_cipher_suites
is no longer supported. Servers now select the best mutually supported cipher suite automatically based on the logic that considers inferred client hardware, server hardware, and security.
Upgrade to CE v2.3
Configuration changes needed to upgrade to v2.3:
- The flag
tls.allow_insecure_connections
is now marked as deprecated because it has moved toclient_tls.allow_insecure_connections
. The support undertls
will be removed in the next version.
Upgrade to CE v2.2
Configuration changes needed to upgrade to v2.2:
This version does not require any configuration change.
Upgrade to CE v2.1
Configuration changes needed to upgrade to v2.1:
This version does not require any configuration change.
Upgrade to v2.0 from v0.x or v1.x
The KrakenD 2.0 release is a major version that simplifies the configuration of v1.x
and standardizes field names that were using different criteria to declare the attributes. The migration tool allows you to migrate from KrakenD 0.x
or 1.x
to 2.0
How to use the legacy migration tool
- Use
git
or similar DVCS to track the changes. Compare the differences at the end. - Download the configuration migration tool and execute it passing the path to your KrakenD project
- Review the changes the migration tool did to your config and start the config with the new version
If you have custom go plugins, recompile them. KrakenD has now a command krakend check-plugin
and krakend test-plugin
to test them.
whitelist
or blacklist
will be replaced by allow
and deny
. Make sure to check the changes in the configuration and ensure that the migration tool didn’t change any endpoint definition using those names.The migration tool will take care of what is described below for you, and is actually quite simple. For the most part, what it does is to rename configurations and namespaces. The following list is what it takes care of:
Renamed namespaces
The most visible change is that all non-core components (this is everything outside of Lura) were declared inside an extra_config
section, using a looong namespace. That namespace contained what could look like a URL (e.g., github.com/devopsfaith/krakend-jose/validator
) and generated frequent misunderstandings year after year. Now, all namespaces have been categorized and simplified to a description of their functionality (e.g., auth/validator
).
See the migration tool’s source code for the complete list of renamed namespaces.
Consistent attribute naming
Another relevant change is that some attributes have been renamed to be consistent across all configurations. Prior to 2.0, some attributes used hyphenation (hyphen-ation
), while others used snake case (snake_case
) or camel case (camelCase
). Now, we use snake_case
everywhere if possible.
Removed deprecated elements
The final change is that all functionalities and attributes marked as deprecated in 1.4 have been removed.
whitelist
is removed, and onlyallow
is recognized nowblacklist
is removed, and onlydeny
is recognized nowkrakend-etc
is no longer included in the binarykrakend-consul
, the integration of consul for the JWT revoker, is no longer included in the binary.
Summing up, see the before and after of the following snippet which has 3 of the changes mentioned above.
KrakenD 1:
{
"endpoint": "/foo",
"extra_config": {
"github.com/devopsfaith/krakend-jose/validator" {
"alg": "RS256",
"jwk-url": "https://url/to/jwks.json"
}
},
"backend": [
{
"url_pattern": "/foo",
"whitelist": ["field1", "field2"]
}
]
}
KrakenD 2: Differences highlighted
{
"endpoint": "/foo",
"extra_config": {
"auth/validator": {
"alg": "RS256",
"jwk_url": "https://url/to/jwks.json"
}
},
"backend": [
{
"url_pattern": "/foo",
"allow": ["field1", "field2"]
}
]
}
Contribute to KrakenD Documentation. Improve this page »