News KrakenD CE v2.8 released with improved Lua and OpenTelemetry

Document updated on Jan 31, 2021

Enterprise plugins

Some of the functionality offered by KrakenD Enterprise is presented as plugins, and other as components. Although functionality offered as plugins is decreasing, it’s important to understand a few concepts and particularities of plugins before you start using them. For each functionality of Enterprise offered as a plugin, you will see in its documentation how to use it.

What is a plugin?
A plugin is a soft-linked library; thus, a separated binary file (.so), that when running in conjunction with KrakenD, can participate in the processing. Plugins and middlewares are close concepts, but while middlewares are part of the KrakenD binary, plugins are not.

Understanding plugins

KrakenD offers functionality using different strategies. Without entering in a lot of detail, we’ll say that both the Community Edition (CE) and the Enterprise Edition (EE) products are final binaries built through the composition of the Lura framework, which brings the basic API Gateway functionality, and many other pieces to extend its capabilities. We refer to all these extra surrounding pieces as middleware or components and are usually configured using the (probably) already familiar extra_config. The “extra” comes from the “you are not part of the core functionality”.

Available plugins and types

All available Enterprise plugins, in any distribution form (Linux package or Docker), are copied in the folder /opt/krakend/plugins. If you do a ls on the folder, you’ll see many .so files. These are the binaries that KrakenD could soft-link and load during startup. All plugins have their documentation.

You can see the list of plugins available today with a ls /opt/krakend/plugins or:

Getting the plugins list from a terminal 

$docker run --rm --entrypoint=/bin/ls krakend/krakend-ee:2.7.6 /opt/krakend/plugins

There are four types of plugins in KrakenD:

  1. HTTP handler plugins (router plugins): Let you modify the request of the user before KrakenD starts processing in the router layer
  2. HTTP client plugin (proxy plugins): Let you change how KrakenD interacts (as a client) with your backend services.
  3. Response modifier plugins](/docs/extending/plugin-modifiers/): Let you modify the responses received from your backends
  4. Request modififer plugins: Let you modify the requests sent to your backends

The place where each plugin acts is depicted here:

Types of plugins

Enabling Enterprise plugins

KrakenD registers plugins during startup according to its plugin configuration:

{
    "version": 3,
    "plugin": {
        "pattern":".so",
        "folder": "/opt/krakend/plugins/"
    }
}

You must add the plugin keyword at the root of your configuration to let KrakenD know the rules to register plugins during startup.

  • folder: The path in the filesystem where all the plugins you want to load are. MUST END IN SLASH. The folder can be a relative or absolute path. KrakenD Enterprise has in the path /opt/krakend/plugins/ all plugins.
  • pattern: The pattern narrows down the contents of the folder. It represents the substring that must be present in the plugin name to load. In the example above, any plugin with the .so extension will be loaded. You could also use any prefix or suffix to match the content or even the full name of a single plugin. For instance, if you just want to load the rewrite plugin, use "pattern":"krakend-rewrite.so", and prevent loading unwanted plugins.
Avoid loading all plugins

Through all the documentation, and for an easier reference when testing and copy-pasting, all examples load all the Enterprise plugins in the system as the folder /opt/krakend/plugins is passed.

The best practice is either copy, move, symlink, or delete plugins in your Dockerfile to leave only what you need.

At this point and with the previous configuration, you have registered plugins. The next step is to start using them.

Declaring router plugins

All router plugins are declared at the root level of the configuration file. You need to list all the plugins that will act in the name list. The order is important (we will see it in a while). The configuration looks like this:

{
    "version": 3,
    "plugin": {
        "pattern":".so",
        "folder": "./plugins-in-use/"
    },
    "extra_config": {
        "plugin/http-server": {
            "name": ["plugin1", "plugin2", "..." ],
            "plugin1": {
                "settings-of-plugin1": "here"
            },
            "plugin2": {
                "settings-of-plugin2": "here"
            }
        }
    }
}

As you can see you need a top-level extra_config with the plugin/http-server key. An inside the following:

  • name: The list of all the plugins that have to be loaded
  • plugin1: Replace plugin1, plugin2, etc., by the name of the plugins you have declared in the name list.

Declaring backend plugins

Backend plugins need to declare inside the backends’ extra_config the namespace plugin/http-client. An inside the name of the plugin you want to load. Each backend can load only one plugin. For instance:

{
    "endpoint": "/redirect",
    "output_encoding": "no-op",
    "backend": [
        {
            "url_pattern": "/__debug",
            "encoding": "no-op",
            "extra_config": {
                "plugin/http-client": {
                    "name": "no-redirect"
                }
            }
        }
    ]
}

Multiple plugins and execution order

You can add only one proxy plugin for each backend, while you can have multiple router plugins as you have seen before. Router plugins modify the request of the user before KrakenD starts processing it. They can even prevent that the request reaches KrakenD at all, so make sure the order is as you expect.

Let’s simplify the names of the plugins for better understanding. If we define a configuration like this one:


{
    "plugin/http-server": {
        "name": ["A", "B", "C" ]
    }
}

Then KrakenD will wrap their execution in a function like this: A(B(C())). The outcome is that the last plugin C is executed in the first place, then its result passes to B, and then to A.

Verifying correct load of plugins

When KrakenD starts, you can see which plugins are loaded in the log. This is an example of some lines:

virtualhost handler plugin loaded!!!
url-rewrite handler plugin loaded!!!
...
2020/01/31 20:20:40  DEBUG: http-server-handler: injecting plugin url-rewrite

If the plugin failed to load for whatever reason, you can see it too:

2020/01/31 20:23:50  WARNING: loading plugins: plugin loader found 10 error(s):
opening plugin 0 (/opt/krakend/pluginsbasic-auth.so): plugin.Open("/opt/krakend/pluginsbasic-auth.so"): realpath failed

In the previous example, the folder configuration didn’t end in a slash.

Scarf

Unresolved issues?

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.

See all support channels