krakendio / krakend-documentation

All the documentation under http://www.krakend.io/docs/

KrakenD Documentation

All the documentation uses Markdown syntax and the site is generated using Hugo. After your contribution this repository will be used to compile all the documentation.

If you want to use a server to browse this pages, although not necessary, you can copy the folder inside the content directory in any Hugo installation.

Contribute!

Feel free to fork this repository and contribute to a better KrakenD documentation.

If you'd like to add a new language please open an issue before doing the work as we will need to add the support before it is visible.

Thanks for improving the docs!

Helpers when writing

Besides from the regular Markdown to write content, there are a few shortcodes to help you style the documentation:

Add a yellow note:

For important notes, and things that need special, attention:

{{< note title="A note on JWT generation" >}}
Some big yellow block with a note
{{< /note >}}

Show terminal output:

The CSS will prepend a dollar sign $ in the first line.

{{< terminal title="Title of the box">}}
docker build -t mykrakend .
Sending build context to Docker daemon   5.12kB
Step 1/2 : FROM devopsfaith/krakend
---> c7e33ec819c0
Step 2/2 : COPY krakend.json /etc/krakend/krakend.json
---> 703818e9de3a
Successfully built 703818e9de3a
Successfully tagged mykrakend:latest
{{< /terminal >}}

Highlight some code:

Most of the code is just idented with a tab and Markdown renders it properly as a <pre> tag and we prefer not to colorize it much. Nevertheless this can be done with the following shortcode:

{{< highlight json >}}
{ "a": true }
{{< /highlight >}}

You can also highlight a line, specific lines 6 7, or a range 6-8:

{{< highlight go "hl_lines=6-7" >}}
package krakend

import (
    "github.com/devopsfaith/krakend/logging"
    client "github.com/devopsfaith/krakend/transport/http/client/plugin"
    server "github.com/devopsfaith/krakend/transport/http/server/plugin"
)
{{< /highlight >}}

The documentation of the attributes is autoloaded from its json schema definition. You will find lines like the following:

{{< schema data="folder/file.json" >}}

The data attribute loads the file from the krakend-schema repository, using the same path.

krakend-documentation's Issues

Document request and response modifier plugins

luraproject/lura#473

Logging, metrics and tracers

• Types of metrics you can see (timers, gauges, histograms… of your requests)
• Metrics (/__stats endpoint)
• Using the metrics
  - Sending metrics to Influx
• Logger (logrus, logstash)
  - Opencensus Exporters
  - Send traces to InfluxDB
  - Send traces to Zipkin
  - Send traces to Prometheus
  - Send traces to Jaeger
  - Send traces to Logger

OAuth2 clientcredentials

Add doc regarding the https://github.com/devopsfaith/krakend-oauth2-clientcredentials module

Add documentation regarding request executor and http handler plugins

... extending a little more the description provided at https://www.krakend.io/blog/krakend-grpc-gateway-plugin/

Include append operation

the flatmap feature is being extended with the append operation (as per krakend/flatmap#4).

Given this configuration

{
    "type": "append",
    "args": ["collection2", "collection"]
}

and this response from the backend

{
	"collection": [1,2,3]
	"collection2": [10,20,30]
}

the gateway will generate this response

{
	"collection": [1,2,3,10,20,30]
}

Document influxdb exporter for the custom metrics module

We could use the current example from the repo: https://github.com/letgoapp/krakend-influx/tree/master/examples

Document how to enable extra tags on the prometheus exporter

krakend/krakend-opencensus#27

Improve SD documentation

neither the etcd nor the dns sections mention the required "disable_host_sanitize": true option

Fix martian examples

the martian configuration should be placed at the backend level.

Document the JWT claims extraction

Since 1.2.0 it is possible to use first level claims from the JWT in the url pattern definition:

"url_pattern": "/foo/{JWT.sub}"

Notice that accepting such notation at the configuration is independent from the extractor (that's on the JOSE validator). If the JOSE validator is not defined and a JWT claim is used at the url pattern, the final url will contain the placeholder (the backend will get a request to /foo/{JWT.sub})

JWT needs more explanation ¯\_(ツ)_/¯

Given the number of requests we have around JWT usage, although this is not linked to the gateway we should at least:

• Explain that JWK keys need to be in base64 urlencoded
• JWT needs the kid in the header

Plain HTTP download

On https://www.krakend.io/download/ the download (Download tgz) is served with plain http. Additionally:

• manually changing the url to https doesn't work
• the GitHub releases doesn't contain binaries
• the SHA is served with plain HTTP

There are other options but it is nice that with go I can download binaries, but without https this option seems unwieldy.

Add documentation for cache_duration in JWS

The last PR from @foxcool adds the cache_duration key in the JSON file. Add in in the docs:

https://github.com/devopsfaith/krakend-documentation/blob/mastecache_durationr/authorization/jwt-validation.md

Add documentation for static proxy

The static proxy is not documented.

• It injects static data into the response before returning it to the router.
• It supports different strategies for deciding if the static data should be added or not

Here, an example from the integration tests: https://github.com/devopsfaith/krakend/blob/master/test/krakend.json#L9-L30

supported strategies:

• always
• success
• errored
• complete
• incomplete

what do they mean? https://github.com/devopsfaith/krakend/blob/master/proxy/static.go#L100-L104

Add a note about signing + other handlers (e.g: signing)

See:
krakend/krakend-ratelimit#15

Lua and Rate-Limit are injected after JOSE, so they won't act.

Add CEL example in the documentation

Add a configuration example in the docs (https://www.krakend.io/docs/endpoints/common-expression-language-cel/)

Example: https://github.com/devopsfaith/krakend-cel/blob/master/example/krakend.json

Include a reference to "roles_key_is_nested"

the jwt validation section does not describe the flag roles_key_is_nested, required to be able to check roles in nested structures

Add Proxy and Route Plugin Examples

• An explanation of the basic structure of plugins would be helpful to get started
• A few very basic examples of plugins would be helpful as well

Explain the two different KrakenD pipes flows

Explicit document to differentiate the two different types of pipes there are at KrakenD:

• regular pipe
• noop (request can only be manipulated with a Lua script)

Developer tools documentation

Add documentation regarding TLS config

The struct definition: https://github.com/devopsfaith/krakend/blob/master/config/config.go#L228-L237

Throw into the trash the terms blacklist and whitelist

From KrakenD 1.2 all terms whitelist and blacklist must disappear. The corresponding functionality will be configured using allow and deny.

flatmap accepts multiple values on deletion

luraproject/lura#430

Update JOSE documentation

So this new features are documented:

• krakend/krakend-jose#48
• krakend/krakend-jose#45
• krakend/krakend-jose#41

Explain how In memory cache (httpcache) works

Add documentation for the botdetection module

Sample configuration: https://github.com/devopsfaith/krakend-ce/blob/b6924a2a0d7fafe9517d65c20f535f737b7be5cd/tests/fixtures/krakend.json#L25-L32

notice it also accepts a fourth param "cacheSize" (int). If 0, no cache layer is added. For other values, the module adds a LRU-based cache layer on top of the detector

Martian modifiers documentation

Document the proxy flatmap module

this PR (luraproject/lura#395) introduces a new flatmap proxy at the proxy pipe, allowing users to manipulate the result of the merge operation.

the configuration has the same struct and the same namespace, but ir should be placed at the endpoint's extra config

Complete flexibleconfig documentation

the sub templates feature is not covered by the current documentation.

• env var FC_TEMPLATES for custom folder where sub templates should be loaded from
• sub templates are included with the function template (from the golang stdlib)

{{template "name" pipeline}}
	The template with the specified name is executed with dot set
	to the value of the pipeline.

Add no-op encoding

there is no reference to the no-op encoders (neither output_encoder nor encoder)

Add lambda module documentation

https://github.com/devopsfaith/krakend-lambda

Document how to return collections

luraproject/lura#475

Add CORS documentation

the CORS module is not documented

BloomFilter Guide

Hello i've been wanting to configure the bloomfilter plugin
therefore ive been looking for documentation and could not find much information about how to set it up within krakenD, it would be great if you can make a how to guide on how to setup the bloomfilter

something like how to configure the the bloomfilter in the config, as well as to have an example of sending a token which then gets declined by the gateway.

JSON Schema validation

Outdated benchmarks

Hi there!

I'm your colleague from Tyk.io :)

I noticed that benchmarks you have on the website are 4-5 years old (if we talking about https://github.com/varnish/api-gateway-benchmarks). And on your comparison page, you also say that it was last run "August 2015".

Since you mention this numbers also on your landing page, it would be at least fair to re-run benchmarks with a new Kong and Tyk versions. At the moment such old tests work against you.

I'm happy to help with the benchmarking suite if you will be interested!

Cheers!

Add del method description

see krakend/krakend-lua#17

Add a section over the status code policy

extending luraproject/lura#288 (comment)

Document new flexibleconfig helpers

krakend/krakend-flexibleconfig#13

Add `detailed_error` in the documentation

Add in the documentation that the failed response from the backend can be passed using the detailed_error feature

Traffic shadowing docs

Explain how to use shadow backends

Document flatmap filtering

Supported operations:

• Delete by matching pattern
• Move from src pattern to dst pattern

Pattern rules:

• Keys are separated by .
• * is a wildcard and matches any kind of key (property name or collection element)

Sample backend definition with flatmap filter:

 {
    "host": [ "http://127.0.0.1:8081" ],
    "url_pattern": "/collection/{id}",
    "is_collection": true,
    "extra_config": {
        "github.com/devopsfaith/krakend/proxy": {
            "flatmap_filter": [
                {
                    "type": "move",
                    "args": ["collection", "paths"]
                },
                {
                    "type": "del",
                    "args": ["paths.*.i"]
                },
                {
                    "type": "move",
                    "args": ["paths.*.path", "paths.*.url"]
                }
            ]
        }
    }
}

notice: when the flatmap filter is enabled, the withelist, blacklist and mapping attributes are ignored (group and target are still in use).

Move patterns (src => dst):

src	dst	allowed
"a.*.b.*.c"	"a.*.b.*.d"	👍
"a.*.b.*.c"	"a.*.c"	👎
"a.b.c"	"c"	👍
"a.*.b.c"	"c"	👎
"a.*.b.c"	"a.*.b.*.d.*.e"	👎
"a.*.b.*.c"	"a.*.b.*.c.d.e.f.g"	👍
"a.*.b.*.c"	"a.*.x.*.c.d.e.f.g"	👎
"a.*.b.*.c"	"a.*.x.*.c"	👎

JWT scope validation, propagate claims

krakend/krakend-jose#48
krakend/krakend-jose#45
krakend/krakend-jose#41

Datadog exporter

• namespace
• service
• trace_address
• stats_address
• tags
• global_tags
• disable_count_per_buckets

See: https://godoc.org/github.com/DataDog/opencensus-go-exporter-datadog#Options

Add most common providers in the JWT validation page

E.g:
Azure AD, Google Firebase, Keycloak, etc....

Raised:
https://gophers.slack.com/archives/CANCJD0V8/p1605796692371800?thread_ts=1605786743.342900&cid=CANCJD0V8

Document `del` method for lua tables

krakend/krakend-lua#17

Propagate claims

Add documentation for this feature:
krakend/krakend-jose#45

Override configuration using ENV vars

Explain how to override specific values in the configuration using env vars. E.g: VERSION

Add pub/sub documentation

krakend/krakend-pubsub#2

New backends:

• AWS SNS (Simple Notification Service) and SQS (Simple Queueing Service)
• Azure Service Bus Topic and Subscription
• GCP PubSub
• NATS.io
• RabbitMQ

Circuit Braker accepts a name

every CB can be named so their logs can be enriched with it