News KrakenD CE v2.6 released with OpenTelemetry

Enterprise Documentation

Recent changes

Backend Configuration in KrakenD API Gateway

Document updated on Jun 28, 2023

The concept of backend refers to the origin servers providing the necessary data to populate your endpoints. A backend can be something like your HTTP-based API, a Lambda function, or a Kafka queue, for example.

A backend can be any server inside or outside your network if it is reachable by KrakenD. For instance, you can create endpoints fetching data from your internal servers and enrich them by adding third-party data from an external API like Github, Facebook, or other services. You can also return everything aggregated in a single glorified response.

A backend object is an array of all the services that an endpoint connects to. It defines the list of hostnames connected to and the URL to send or receive the data. If a backend has more than one host, then the array is the egress load balancing list.

When a KrakenD endpoint is hit, the engine requests all defined backends in parallel (unless a sequential proxy is used) and the content merged and aggregated (unless you just proxy using the no-op encoding). The returned content is parsed according to its encoding or in some cases its extra_config configuration.

Multiple non-safe methods

Even though you can use several backends in one endpoint, KrakenD does not allow you to define multiple non-safe (write) backends. This is a (sometimes controversial) design decision to disable the gateway to handle transactions.

If you need to have a write method (POST, PUT, DELETE, PATCH) together with other GET methods, use the sequential proxy and place a maximum of 1 write method at the end of the sequence.

Backend/Upstream configuration

Inside the backend array, you need to create an object for each upstream service used by its declaring endpoint. The combination of host + url_patternset the full URL that KrakenD will use to fetch your upstream services. Most of the backends will require a simple configuration like:

{
    "host": ["http://your-api"],
    "url_pattern": "/url"
}

The url_pattern accepts {variables} from the endpoint definition, and on Enterprise you can also inject headers with patterns like /{input_headers.X-Tenant}/foo

All the options relative to the backend definition are:

Fields of Backend Object "backend"
* required fields
allow

array
Only return the fields in the list. Only the matching fields (case-sensitive) are returned in the final response. Use a dot . separator to define nested attributes, e.g.: a.b removes {"a":{"b": true}}
Example: "token" , "CVV" , "password"
deny

array
Don’t return the fields in the list. All matching fields (case-sensitive) defined in the list, are removed from the response. Use a dot . separator to definr nested attributes, e.g.: a.b removes {"a":{"b": true}}.
disable_host_sanitize

boolean
Set it to true when the host doesn’t need to be checked for an HTTP protocol. This is the case of sd=dns or when using other protocols like amqp://, nats://, kafka://, etc. When set to true, and the protocol is not HTTP, KrakenD fails with an invalid host error.
Defaults to false
encoding

string
Defines your needed encoding to set how to parse the response. Defaults to the value of its endpoint’s encoding, or to json if not defined anywhere else.
Possible values are: "json" , "safejson" , "fast-json" , "xml" , "rss" , "string" , "no-op"
Defaults to "json"
extra_config

object
When there is additional configuration related to a specific component or middleware (like a circuit breaker, rate limit, etc.), it is declared under this section.
group

string
Instead of placing all the response attributes in the root of the response, create a new key and encapsulate the response inside.
Defaults to "backend1"
host

array
An array with all the available hosts to load balance requests, including the schema (when possible) schema://host:port. E.g.: https://my.users-ms.com. If you are in a platform where hosts or services are balanced (e.g., a K8S service), write a single entry in the array with the service name/balancer address. Defaults to the host declaration at the configuration’s root level, and the service fails starting when there is none.
input_headers

array
A second level of header filtering that defines the list of all headers allowed to reach this backend when different than the endpoint.
By default, all headers in the endpoint input_headers reach the backend, unless otherwise specified here. An empty list [] is considered a zero-value and allows all headers to pass. Use [""] to explicitly remove all headers. See headers forwarding
Defaults to []
input_query_strings

array
A second level of query string filtering that defines the list of all query strings allowed to reach this backend when different than the endpoint.
By default, all query strings in the endpoint input_query_strings reach the backend, unless otherwise specified here. An empty list [] is considered a zero-value and allows all headers to pass. Use [""] to explicitly remove all query strings. See query strings forwarding
Defaults to []
is_collection

boolean
Set to true when your API does not return an object {} but a collection []
Defaults to true
mapping

object
Mapping, or also known as renaming, let you change the name of the fields of the generated responses, so your composed response would be as close to your use case as possible without changing a line on any backend.
Example: {"from":"to"}
method

string
The method sent to this backend in uppercase. The method does not need to match the endpoint’s method. When the value is omitted, it uses the same endpoint’s method.
Possible values are: "GET" , "POST" , "PUT" , "PATCH" , "DELETE"
Defaults to "GET"
sd

string
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"
sd_scheme

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

string
Removes the matching object from the reponse and returns only its contents.
Example: "data" , "content" , "response"
url_pattern  *

string
The path inside the service (no protocol, no host, no method). E.g: /users. Some functionalities under extra_config might drop the requirement of declaring a valid url_pattern, but they are exceptions. The URL must be RESTful, if it is not (e.g.: /url.{some_variable}.json), then see how to disable RESTful checking.
Example: "/users" , "/user/{id_user}"

Other configuration options such as the ones for data manipulation are available. You will find them in each specific feature section.

Backend configuration example

In the example below, KrakenD offers an endpoint /v1/products that merges the content from two different services using the URLs /products and /offers. The marketing (marketing.myapi.com) and the products (products-XX.myapi.com) API requests are fired simultaneously. KrakenD will load-balance among the listed hosts (here or in your service discovery) to pick one of the three hosts.

{
    "endpoints": [
        {
            "endpoint": "/v1/products",
            "method": "GET",
            "backend": [
                {
                    "url_pattern": "/products",
                    "host": [
                        "https://products-01.myapi.com:8000",
                        "https://products-02.myapi.com:8000",
                        "https://products-03.myapi.com:8000"
                    ]
                },
                {
                    "url_pattern": "/offers",
                    "host": [
                        "https://marketing.myapi.com:8000"
                    ]
                }
            ]
        }
    ]
}

Disable RESTful checking

By default KrakenD only works with RESTful URL patterns to connect to backends. Enable the option disable_rest in the root of your configuration if you have backends that aren’t RESTful, e.g.: /url.{some_variable}.json

{
  "$schema": "https://www.krakend.io/schema/v2.5/krakend.json",
  "version": 3,
  "disable_rest": true,
  "endpoints": [
    {
      "endpoint": "/foo",
      "backend": [
        {
          "host": [
            "http://mybackend"
          ],
          "url_pattern": "/url.{some_variable}.json"
        }
      ]
    }
  ]
}

Connecting to HTTPS backends with self-signed certificates

When using self-signed certificates in your backends, you must add the certificates to the local CA, or at least add them while developing the allow_insecure_connections setting to true. Example:

{
  "version": 3,
  "client_tls": {
        "allow_insecure_connections": true
  },
  "endpoints": []
}
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.

We use cookies to understand how you use our site and to improve your overall experience. By continuing to use our site, you accept our Privacy Policy. More information