Document updated on Jun 28, 2023
Backend Configuration in KrakenD API Gateway
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.
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_pattern
set 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
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}}
Examples:"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 ofsd=dns
or when using other protocols likeamqp://
,nats://
,kafka://
, etc. When set to true, and the protocol is not HTTP, KrakenD fails with aninvalid host
error.Defaults tofalse
encoding
- Defines your needed encoding to set how to parse the response. Defaults to the value of its endpoint’s
encoding
, or tojson
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 thehost
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 endpointinput_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 forwardingDefaults 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 endpointinput_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 forwardingDefaults 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
- 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
- The Service Discovery system to resolve your backend services. Defaults to
static
(no external Service Discovery). Usedns
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.Examples:
"http"
,"https"
Defaults to"http"
target
string- Removes the matching object from the reponse and returns only its contents.Examples:
"data"
,"content"
,"response"
url_pattern
* string- The path inside the service (no protocol, no host, no method). E.g:
/users
. Some functionalities underextra_config
might drop the requirement of declaring a validurl_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.Examples:"/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": []
}