Upgrading KrakenD from an older version

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.

Upgrade steps

1. Review the changelog. This document provides a chronological list of releases detailing new features, bug fixes, and possible breaking changes between major versions.
2. 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.
3. 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 EE v2.6 (latest)

OpenTelemetry integration, extended plugin capabilities, updated Grafana Dashboard, and JWT fixes. Configuration changes for v2.6:

• Removed from schema previosuly deprecated fields allow_insecure_connections in the root. Must be declared under client_tls.allow_insecure_connections now.
• Removed from schema previously deprecated prefetch_size and prefetch_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 EE v2.5

The v2.5 introduces API Monetization, allows multiple POSTS in and out sequential calls, adds a license command and listening to a specific IP, and improves Flexible Configuration, E2E tests, OpenAPI, and more. Configuration changes for v2.5:

• The flag router.use_h2c has moved to the root level as use_h2c, and its usage inside the router is marked as deprecated.

Upgrade to EE v2.4

The v2.4 introduces powerful features such as the Catch All (or No-route, or Fallback), the Advanced Flexible Configuration, response manipulation using templates, improves gRPC, or the conversion of some plugins to native functionality. It also includes all features and fixes of Community 2.4.3. Check out the rest of features. Configuration changes for v2.4:

• The static filesystem plugin has been deprecated. Upgrade to the native functionality.
• The virtual host plugin has been deprecated. Upgrade to the native functionality.
• The Instana integration was deprecated in previous versions and has been removed.
• The Google Analytics integration was deprecated in previous versions and has been removed.
• When the license is missing or expired, the Enterprise binary will not try to run in open source mode as there might be security implications, such as not understanding security policies.
• The flag tls.allow_insecure_connections has been relocated under client_tls.allow_insecure_connections in v2.3, and the old location 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 EE v2.3

The v2.3 includes awaited new features requested by customers, such as gRPC backends without plugins, easier wildcards (simply writing a star *), and the End-to-End testing with JSON Schema contracts. It also includes all features and fixes of Community 2.3.2. Checkout the rest of features. Configuration changes for v2.3:

• The prefetch_size flag on AMQP was never implemented, and it has been removed from the configuration
• The prefetch_count has been removed from AMQP producers as it only makes sense in a consumer scenario
• The krakend generate openapi command has been renamed to krakend openapi export; please replace its usages.
• The krakend generate from openapi command has been renamed to krakend openapi import; please replace its usages.
• The HTTP proxy plugin is deprecated as the functionality is natively supported as an HTTP Client option.
• The no-redirect plugin is deprecated as the functionality is natively supported as an HTTP Client option.
• The allow_insecure_connections property at the service level now moves under client_tls > allow_insecure_connections.
• The Instana integration is deprecated and will be removed in future releases.
• The Google Analytics integration is deprecated and will be removed in future releases.

Upgrade to EE v2.2

The v2.2. introduces a new security policies engine, routing based on headers, OpenAPI 3, SOAP integration with custom body generation, everything on Community 2.2.1, and more. Configuration changes for v2.2:

This version does not require any configuration change.

Upgrade to EE v2.1

KrakenD Enterprise v2.1 brings a lot of new functionality, including advanced manipulation with a JSON Query language, a Revoke Server to manage tokens in clusters, new Kibana and Grafana dashboards, faster encoding, a rewritten and richer NewRelic exporter, Websockets balancing, everything on Community 2.1.2, and much more. Configuration changes for v2.1:

• The –accept-eula (or -e) flag is no longer necessary to start KrakenD and should be removed
• The telemetry/opencensus component for NewRelic will stop working in future versions. Use telemetry/newrelic instead.

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.

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 only allow is recognized now
• blacklist is removed, and only deny is recognized now
• krakend-etc is no longer included in the binary
• krakend-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"]
        }
    ]
}