News KrakenD CE v2.7 released with better rate-limiting and security options

Enterprise Documentation

Recent changes

Service Discovery Integration

Document updated on Dec 20, 2023

The service discovery (sd) is an optional attribute of the backend section that enables KrakenD to detect and locate services automatically on your enterprise network.

Related read
You might also want to read the Load Balancer documentation

The chosen service discovery strategy determines how to retrieve (statically or dynamically) the final list of IPs, hostnames, or services pointing to your backends. If your host list is dynamic, you can use an external service discovery provider and let KrakenD interact with it to get the hosts. If your host list is static (it doesn’t change) or you use a service name or an external load balancer, you can use static resolution and directly use the values provided under host[].

KrakenD must be in a network that can reach any declared hosts. With more than one host, KrakenD load balances the connections to the hosts in the list.

Service discovery configuration

The possible configurations and values for sd are:

Fields of "backend"
* required fields

The Service Discovery system to resolve your backend services. Defaults to static (no external Service Discovery). Use dns to use DNS SRV records.
Possible values are: "static" , "dns"
Defaults to "static"

The Service Discovery scheme to connect to your backend services.
Examples: "http" , "https"
Defaults to "http"

Static resolution

The static resolution is the default service discovery strategy. It implies that you write directly in the configuration the protocol plus the service name, hosts, or IPs you want to connect to.

The static resolution uses a list of hosts to load balance (in a Round Robin fashion) all servers in the list, and you should expect more or less an equivalent number of hits on each backend. However, if you use a Kubernetes service, then it load-balances itself so that you only need one entry.

Declaring hosts on Kubernetes
When the consumed hosts are behind a balancer or a service name, write a single entry in the array with that name.

To use static resolution, you don’t need to declare anything other than the host list. However, you can add the "sd": "static" property in the backend configuration for a more explicit reading, as it is the default value when sd is not declared). Example:

"backend": [
        "url_pattern": "/some-url",
        "sd": "static",
        "host": [

DNS SRV Service Discovery (Kubernetes/Consul)

The DNS SRV(see RFC) is a market standard used by systems such as Kubernetes, Mesos, Haproxy, Nginx plus, AWS ECS, Linkerd, and many more. An SRV entry is a custom DNS record that establishes connections between services. When KrakenD needs to know the location of a specific service, it will search for a related SRV record.

The format of the SRV record is as follows: TTL IN SRV priority weight port target

Example. A service running on port 8000 with maximum priority (0) and a weight 5 ): 86400 IN SRV 0 5 8000
The DNS-based service discovery caches entries for 30 seconds.

To integrate Consul, Kubernetes, or any other DNS SRV compatible system as the Service Discovery, you only need to set two keys:

  • "sd": "dns": To use dynamic host resolution using the service discovery strategy
  • "sd_scheme": "https": When the list of hosts provided by the service discovery is offered under HTTPS instead of plain HTTP
  • "host": []: And entry with the service name providing the resolution (e.g., Consul address)

Add these keys in the backend section of your configuration. If there is another host key in the root level of the configuration, you don’t need to declare it here if the value is the same.

For instance:

    "backend": [
            "url_pattern": "/foo",
            "sd": "dns",
            "sd_scheme": "https",
            "host": [
            "disable_host_sanitize": true

With the configuration above, KrakenD will query every 30 seconds the DNS and will apply to the internal balancer any weights and priorities returned by the DNS record.

How priority and weight affect balancing

When the Service Discovery answers with the list of hosts, only the lower priority is taken. For instance, if you have a response like this one:

SRV response example 
$dig SRV +short
10 1 8000
10 2 8000
20 1 8000

Which can be read as two services with priority 10 and one with 20, all using port 8000.

With this configuration, KrakenD removes service-3 (prio 20) from the balancing since two entries have lower priority (prio 10).

In addition, the weight of service-1 is 1, and service-2 is 2, so the final list where KrakenD will load-balance is: ["service-1:8000", "service-2:8000", "service-2:8000"]


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.