Document updated on Oct 25, 2022

Wildcard routes

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

Let’s say you define the wildcard pattern /foo. It will react to URLs like /foo, /foo/a?x=1, /foo/a/b/c/d, /foo/*, etc. But /foobar won’t work as /foobar is not a subresource of /foo.

Wildcard definitions are not regexp patterns but literal matches of a path (and all its subresources).

The receiving endpoint receives the request in its url_pattern appending everything after the declared wildcard pattern.

Wildcard configuration

When using this plugin, you need to provide two things:

1. The paths that are wildcards (e.g.: /foo), defined in the plugin/http-server section.
2. The receiving endpoints used as the processors of all wildcard traffic (e.g.,/__wildcard/foo), defined in the plugin/http-client section.

We recommend using a specific endpoint prefix so it’s clear to everyone that the endpoint is internal and used for this purpose. In our sample configurations, we use /__wildcard/ as a prefix. Hence, it becomes evident when reading the configuration what it is for, but using /__wildcard/ is not mandatory, and you can use whatever you want or no prefix at all.

If 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 two required blocks of configuration mentioned above are:

1. Wildcard HTTP server plugin

Defines which requests are considered a wildcard and where the traffic is sent to:

{
    "version": 3,
    "plugin": {
        "pattern":".so",
        "folder": "/opt/krakend/plugins/"
    },
    "extra_config": {
        "plugin/http-server": {
            "name": [ "wildcard" ],
            "wildcard": {
                "endpoints": {
                    "/__wildcard/foo": [ "/foo", "/aliasfoo" ]
                }
            }
        }
    }
}

The wildcard plugin has only one configuration map:

2. Wildcard HTTP client plugin

The second block is the HTTP client plugin that enables an endpoint for wildcard processing and appends the full path to the url_pattern. When a user sends a request to /foo/a/b/c the client part appends /a/b/c to the url_pattern you have defined.

{
    "endpoint": "/__wildcard/the-foo",
    "input_headers": [ "X-Krakend-Wildcard" ],
    "backend": [
    {
        "host": [ "http://localhost:8080" ],
        "url_pattern": "/__debug/foo",
        "extra_config": {
            "plugin/http-client": {
                "name": "wildcard",
                "no_redirect": false
            }
        }
    }
    ]
}

• Include "input_headers": [ "X-Krakend-Wildcard" ] in the endpoint definition as it is the internal mechanism used to identidy wildcards. These headers only live inside KrakenD.
• Include an extra_config with the plugin/http-client named wildcard
• Set no_redirect to true if you down’t want KrakenD to follow redirects and let the endpoint consuming user to receive the 30x status code.

Configuration of wildcards

A full example of wildcard configuration is below. KrakenD will take requests like /foo/* and /aliasfoo/* and send them to the KrakenD endpoint /__wildcard/the-foo. All requests to /v1/*will be sent to the /__wildcard/legacy endpoint. Highlighting relevant blocks:

{
    "version": 3,
    "port": 8080,
    "plugin": {
        "pattern":".so",
        "folder": "/opt/krakend/plugins/"
    },
    "extra_config": {
        "plugin/http-server": {
            "name": [ "wildcard" ],
            "wildcard": {
                "endpoints": {
                    "/__wildcard/foo": [ "/foo", "/aliasfoo" ],
                    "/__wildcard/legacy": [ "/v1" ]
                }
            }
        }
    },
    "endpoints": [
       {
            "endpoint": "/__wildcard/foo",
            "input_headers": [ "X-Krakend-Wildcard" ],
            "backend": [
            {
                "host": [ "http://localhost:8080" ],
                "url_pattern": "/__debug/foo",
                "extra_config": {
                    "plugin/http-client": {
                        "name": "wildcard"
                    }
                }
            }
            ]
        },
        {
            "endpoint": "/__wildcard/legacy",
            "input_headers": [ "X-Krakend-Wildcard" ],
            "backend": [
            {
                "host": [ "http://localhost:8080" ],
                "url_pattern": "/__debug/legacy",
                "extra_config": {
                    "plugin/http-client": {
                        "name": "wildcard"
                    }
                }
            }
            ]
        }
    ]
}