Wildcard routes

Document updated on Mar 23, 2021

The krakend-wildcard plugin allows you that URLs starting with known patterns are forwarded to a common endpoint, without needing to declare all possible routes. For instance, you want to forward all traffic to /foo/* (with any nesting levels) to a specific backend.

Adding wildcard routes

Let’s say you define the wildcard pattern /foo. It could match with URLs like the ones below:

• /foo
• /foo/a?x=1
• /foo/a/b/c/d
• /foo/*

Wildcard paths are not regexp patterns, but literal matches of an URL and all its subresources. All the above match with the pattern /foo but /foobar does not. In this plugin you need to provide only two things:

• The wildcard paths (e.g: /foo)
• The endpoint used as the receiver of all matching URLs (e.g.,/__wildcard/foo).

The receiving endpoint is a regular KrakenD endpoint that you will associate to your backend(s). If for instance you want to use multiple methods (PUT, POST, etc.) you will need to create an entry per method (as in any other KrakenD endpoint).

The receiving endpoint will have in the request path its url_pattern + everything after the declared wildcard pattern.

As the receiving endpoint is meant to be used by the plugin to forward the traffic only, we recommend using a distinctive endpoint definition so it’s clear to everyone that the endpoint is used for internal usage. In our sample configuration we are using something like /__wildcard/foo so it is obvious what it is for.

The piece of the configuration that does the job is:

{    "krakend-wildcard": {
        "endpoints": {
            "/__wildcard/the-foo": [ "/foo", "/aliasfoo" ]
        }
    }
}

This configuration will take /foo/* and /aliasfoo/* URLs and send them to the KrakenD endpoint /__wildcard/the-foo. The receiving endpoint can of course have all the features of any KrakenD endpoint (authorization, rate limiting, etc.)

Configuration as HTTP server handler

The wildcard configuration requires a configuration like this one:

{
    "version": 2,
    "port": 8080,
    "plugin": {
        "pattern":".so",
        "folder": "/opt/krakend/plugins/"
    },
    "extra_config": {
        "github_com/devopsfaith/krakend/transport/http/server/handler": {
            "name": [ "krakend-wildcard" ],
            "krakend-wildcard": {
                "endpoints": {
                    "/__wildcard/foo": [ "/foo", "/aliasfoo" ],
                    "/__wildcard/first/second": [ "/v1" ]
                }
            }
        }
    },
    "endpoints": [
       {
            "endpoint": "/__wildcard/foo",
            "headers_to_pass": [ "X-Krakend-Wildcard" ],
            "backend": [
            {
                "host": [ "http://localhost:8080" ],
                "url_pattern": "/__debug/foo",
                "extra_config": {
                    "github.com/devopsfaith/krakend/transport/http/client/executor": {
                        "name": "krakend-wildcard"
                    }
                }
            }
            ]
        },
        {
            "endpoint": "/__wildcard/first/second",
            "headers_to_pass": [ "X-Krakend-Wildcard" ],
            "backend": [
            {
                "host": [ "http://localhost:8080" ],
                "url_pattern": "/__debug/first/second",
                "extra_config": {
                    "github.com/devopsfaith/krakend/transport/http/client/executor": {
                        "name": "krakend-wildcard"
                    }
                }
            }
            ]
        }
    ]
}

Notice that is very important to include "headers_to_pass": [ "X-Krakend-Wildcard" ] as it is the internal mechanism used by the plugin to bypass the KrakenD router.