Document updated on Mar 11, 2024
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.
krakend check --lint
), which is designed to scrutinize your configuration rigorously.The list below is automatically generated based on the changelog.
Configuration changes needed to upgrade to v2.7:
request_definition
of OpenAPI was an object previously {}
, but now is an array of objects [{}]
because multiple requests are possible. Wrap the object in an array.public_key
and private_key
of the tls
configuration have been moved under an array keys
to facilitate multiple certificates and domains. Read moreConfiguration changes needed to upgrade to v2.6:
allow_insecure_connections
in the root. Must be declared under client_tls.allow_insecure_connections
now.prefetch_size
and prefetch_count
attributes from AMQP. These attributes did not have any effect in the software.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.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.Configuration changes needed to upgrade to v2.5:
router.use_h2c
has moved to the root level as use_h2c
, and its usage inside the router
is marked as deprecated.Configuration changes needed to upgrade to v2.4:
tls.allow_insecure_connections
has been relocated under client_tls.allow_insecure_connections
in v2.3, and the old location is no longer supported.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.Configuration changes needed to upgrade to v2.3:
prefetch_size
flag on AMQP was never implemented, and it has been removed from the configurationprefetch_count
has been removed from AMQP producers as it only makes sense in a consumer scenariokrakend generate openapi
command has been renamed to krakend openapi export
; please replace its usages.krakend generate from openapi
command has been renamed to krakend openapi import
; please replace its usages.allow_insecure_connections
property at the service level now moves under client_tls
> allow_insecure_connections
.Configuration changes needed to upgrade to v2.2:
This version does not require any configuration change.
Configuration changes needed to upgrade to v2.1:
–accept-eula
(or -e
) flag is no longer necessary to start KrakenD and should be removedtelemetry/opencensus
component for NewRelic will stop working in future versions. Use telemetry/newrelic
instead.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
git
or similar DVCS to track the changes. Compare the differences at the end.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:
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.
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.
The final change is that all functionalities and attributes marked as deprecated in 1.4 have been removed.
whitelist
is removed, and only allow
is recognized nowblacklist
is removed, and only deny
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"]
}
]
}
The documentation is only a piece of the help you can get! Whether you are looking for Open Source or Enterprise support, see more support channels that can help you.