Document updated on Nov 5, 2020

Virtual Hosts

The Virtual Host plugin allows you to run different configurations of KrakenD endpoints based on the host accessing the server.

For instance, you can declare an endpoint /foo that behaves entirely differently when KrakenD is accessed through a host-a.tld or a host-b.tld. For instance, the same /foo path can have different rate limits or authorization endpoints depending on the called host.

Virtual host configuration

On KrakenD EE the virtual host plugin usually lives inside the /plugins folder. Include the following configuration in your krakend.json to enable virtual hosts:

{
    "version": 2,
    "plugin": {
        "pattern":".so",
        "folder": "/opt/krakend/plugins/"
    },
    "extra_config": {
        "github_com/devopsfaith/krakend/transport/http/server/handler": {
            "name": ["virtualhost", ... ],
            "virtualhost": {
                "hosts": ["host-a.tld", "host-b.tld"]
            }
        }
    }
}

As this is a plugin, there is a shared part in the configuration, such as the plugin key, which defines all Enterprise or custom plugins’ location.

Secondly, as this is a router plugin, it uses the namespace github_com/devopsfaith/krakend/transport/http/server/handler in the global extra_config section, which is common to all router plugins.

Finally, all the router plugins that must be enabled are declared in the name array. In this case, we want to allow the plugin virtualhost.

The configuration keys of this plugin are stored under virtualhost as follows:

• host: All recognized virtual hosts by KrakenD must be listed here. Use the value passed by the client as the Host header.

Declaring endpoints

When you enable the virtual host plugin, all requests to KrakenD (/{path}) that match with a recognized host in the list are rewritten internally to /__virtual/{host}/{path}.

Any request to a host that is not declared in the list does not have this redirection.

Virtual host example

Given the following extra_config configuration:

"extra_config": {
    "github_com/devopsfaith/krakend/transport/http/server/handler": {
        "name": ["virtualhost"],
        "virtualhost": {
            "hosts": ["host-a.yourserver.com", "host-b.yourserver.com"]
        }
    }
}

And the following endpoints:

{
  "version": 2,
  "endpoints": [
    {
      "endpoint": "/foo",
      "backend": [
        {
          "url_pattern": "/__debug/no-host",
          "host": ["http://localhost:8080"]
        }
      ]
    },
    {
      "endpoint": "/__virtual/host-a.yourserver.com/foo",
      "backend": [
        {
          "url_pattern": "/__debug/host-A",
          "host": ["http://localhost:8080"]
        }
      ]
    },
    {
      "endpoint": "/__virtual/host-b.yourserver.com/foo",
      "backend": [
        {
          "url_pattern": "/__debug/host-B",
          "host": ["http://localhost:8080"]
        }
      ]
    }
  ]
}

You can check how /foo hits different endpoints in the following order:

• curl -i -H 'Host: anything' http://localhost:8080/foo: No rewriting placed as host is unknown. Hits the first endpoint.
• curl -i -H 'Host: host-a.yourserver.com' http://localhost:8080/foo: Hits the second endpoint
• curl -i -H 'Host: host-b.yourserver.com' http://localhost:8080/foo: Hits the third endpoint