News New Look, Same Vision: KrakenD’s Website Redesign

Enterprise v2.5 Documentation

You are viewing a previous version of KrakenD Enterprise Edition (v2.5), go to the latest version

Document updated on Jun 28, 2023

Validating the configuration with check

The krakend check command validates KrakenD configuration files written in any of its supported formats.

It’s able to perform three things:

  • Syntax validation - For any format (.yml, .json, .toml, etc)
  • Linting - Besides checking that the file isn’t malformed, the linter checks your config exhaustively against KrakenD’s official schema (repo) to detect wrong types, unknown attributes, or misplaced components. Only available when you work with JSON formats.
  • Testing - It tests a run of the service to catch problems that are not strictly related to linting but to the runtime. For instance, you could declare a colliding endpoint (two endpoints in the same route), and the syntax would validate and lint, yet the configuration would be impossible to run.

The check command can guarantee that a configuration is valid with the three validations.

TL;DR: Add the following line before deploying:

Term 

$krakend check -tlc krakend.json

See the usage below.

Checking the configuration

The krakend check command accepts the following options:

Usage of KrakenD check 

$krakend check --help
╓▄█                          ▄▄▌                               ╓██████▄µ
▐███  ▄███╨▐███▄██H╗██████▄  ║██▌ ,▄███╨ ▄██████▄  ▓██▌█████▄  ███▀╙╙▀▀███╕
▐███▄███▀  ▐█████▀"╙▀▀"╙▀███ ║███▄███┘  ███▀""▀███ ████▀╙▀███H ███     ╙███
▐██████▌   ▐███⌐  ,▄████████M║██████▄  ║██████████M███▌   ███H ███     ,███
▐███╨▀███µ ▐███   ███▌  ,███M║███╙▀███  ███▄```▄▄` ███▌   ███H ███,,,╓▄███▀
▐███  ╙███▄▐███   ╙█████████M║██▌  ╙███▄`▀███████╨ ███▌   ███H █████████▀
                     ``                     `'`

Version: 2.5

Validates that the active configuration file has a valid syntax to run the service.
Change the configuration file by using the --config flag

Usage:
  krakend check [flags]

Aliases:
  check, validate

Examples:
krakend check -d -c config.json

Flags:
  -c, --config string     Path to the configuration filename
  -d, --debug count       Enables the debug
  -h, --help              help for check
  -i, --indent string     Indentation of the check dump (default "\t")
  -l, --lint              Enables the linting against the official KrakenD JSON schema
  -t, --test-gin-routes   Test the endpoint patterns against a real gin router on selected port

Flags

Use krakend check in combination with the following flags:

  • -c or --config to specify the path to the configuration file in any of the supported formats, or to the starting template if used in combination with flexible configuration.
  • -d or --debug (optional) to enable the debug and see information about how KrakenD is interpreting your configuration file. Use from 1 to 3 levels of verbosity using -d, -dd, or -ddd.
  • -t or --test-gin-routes (optional) to test the configuration by trying to start the service for a second. This option is highly recommended as it prevents conflicting routes and other problems unrelated to the linting itself and would end up in a panic.
  • -l or --lint (optional) to check that your configuration file is properly linted and does not contain unrecognized options or wrong types. This option requires Internet access as the schema is downloaded from https://www.krakend.io/schema/v2.5/krakend.json (each version uses its schema).
  • -i or --indent (optional) in combination with -d, to change the indentation when the debug information renders (default: TAB). E.g.: -i "#" uses a hash instead of a tab for every nesting level.
Use –lint to do strict parsing
The command krakend run will run any syntax-valid file, ignoring unknown configuration keys. Use the --lint flag in the check command to find incorrect entries.

Debugging your configuration

You can use three different verbosity levels with the --debug (or -d) flag. The levels are -d, -dd, and -ddd. When used a single time, you get the most relevant information after parsing the configuration, when you add more, you get more and more details. The following example shows the debug of a configuration with one endpoint:

Checking the configuration with the debug flag 

$krakend check -t --lint -d -c krakend.json
Parsing configuration file: krakend.json
Global settings
    Name: My lovely gateway
    Port: 8080
4 global component configuration(s):
- security/bot-detector
- security/cors
- telemetry/logging
- telemetry/metrics
1 API endpoints:
    - GET /cel/req-resp/:id
    Timeout: 3s
    1 endpoint component configuration(s):
    - validation/cel
    Connecting to 2 backend(s):
        [+] GET /__debug/{{.Id}}
        Timeout: 3s
        Hosts: [http://127.0.0.1:8080]
        1 backend component configuration(s):
        - validation/cel

        [+] GET /__debug/{{.Id}}
        Timeout: 3s
        Hosts: [http://127.0.0.1:8080]
        1 backend component configuration(s):
        - validation/cel
1 async agent(s):
    - cool-agent
    1 agent component configuration(s):
    - github.com/devopsfaith/krakend-amqp/agent
    Connecting to 1 backend(s):
        [+] POST /__debug/cool-agent
        Timeout: 3s
        Hosts: [http://127.0.0.1:8080]

Syntax OK!

The same example with the verbosity level 2 (-dd) adds more information in the global settings (like the TLS section) and shows the configuration of the extra_config. The endpoints and the backends also show more information:

Checking the configuration with the debug flag 

$Parsing configuration file: krakend.json
Global settings
    Name: My lovely gateway
    Port: 8080
    Default cache TTL: 1h0m0s
    Default timeout: 3s
    Default backend hosts: []
    No TLS section defined
    No Plugin section defined
4 global component configuration(s):
- security/bot-detector
    deny: [a b]
    patterns: [(Pingdom.com_bot_version_).* (facebookexternalhit)/.*]
    allow: [c Pingdom.com_bot_version_1.1]
- security/cors
    expose_headers: [Content-Length]
    allow_origins: [*]
    max_age: 12h
    allow_methods: [POST GET]
    allow_headers: [Origin Authorization Content-Type]
- telemetry/logging
    prefix: [KRAKEND]
    stdout: true
    level: DEBUG
    syslog: false
- telemetry/metrics
    listen_address: :8090
    collection_time: 60s
1 API endpoints:
    - GET /example/:id
    Timeout: 3s
    QueryString: [q id]
    CacheTTL: 1h0m0s
    Headers to pass: [X-Header]
    OutputEncoding: json
    Concurrent calls: 1
    1 endpoint component configuration(s):
    - validation/cel
        [map[check_expr:'something' in req_headers['X-Header']] map[check_expr:int(req_params.Id) % 2 == 0]]
    Connecting to 2 backend(s):
        [+] GET /__debug/{{.Id}}
        Timeout: 3s
        Hosts: [http://127.0.0.1:8080]
        Concurrent calls: 1
        Host sanitization disabled: false
        Target:
        Deny: [], Allow: []
        Mapping: map[]
        Group: backend1
        Encoding:
        Is collection: false
        SD:
        1 backend component configuration(s):
        - validation/cel
            [map[check_expr:int(req_params.Id) % 3 == 0]]

        [+] GET /__debug/{{.Id}}
        Timeout: 3s
        Hosts: [http://127.0.0.1:8080]
        Concurrent calls: 1
        Host sanitization disabled: false
        Target:
        Deny: [], Allow: []
        Mapping: map[]
        Group: backend2
        Encoding:
        Is collection: false
        SD:
        1 backend component configuration(s):
        - validation/cel
            [map[check_expr:int(req_params.Id) % 5 == 0]]
1 async agent(s):
    - cool-agent
    Encoding:
    Consumer Timeout: 3s
    Consumer Workers: 20
    Consumer Topic: *.bar
    Consumer Max Rate: 0.000000
    Connection Max Retries: 10
    Connection Backoff Strategy: exponential-jitter
    Connection Health Interval: 1s
    1 agent component configuration(s):
    - github.com/devopsfaith/krakend-amqp/agent
        name: krakend
        host: amqp://guest:guest@localhost:5672/
        exchange: foo
        prefetch_count: 40
        auto_ack: true
    Connecting to 1 backend(s):
        [+] POST /__debug/cool-agent
        Timeout: 3s
        Hosts: [http://127.0.0.1:8080]
        Concurrent calls: 0
        Host sanitization disabled: false
        Target:
        Deny: [], Allow: []
        Mapping: map[]
        Group:
        Encoding:
        Is collection: false
        SD:
        0 backend component configuration(s):

Syntax OK!

And in level 3 (-ddd), there is everything that KrakenD could parse from the configuration:

Checking the configuration with the debug flag 

$krakend check -t --lint -ddd -c krakend.json
Parsing configuration file: krakend.json
Global settings
    Name: My lovely gateway
    Port: 8080
    Default cache TTL: 1h0m0s
    Default timeout: 3s
    Default backend hosts: []
    Read timeout: 0s
    Write timeout: 0s
    Idle timeout: 0s
    Read header timeout: 0s
    Idle connection timeout: 0s
    Response header timeout: 0s
    Expect continue timeout: 0s
    Dialer timeout: 0s
    Dialer fallback delay: 0s
    Dialer keep alive: 0s
    Disable keep alives: false
    Disable compression: false
    Max idle connections: 0
    Max idle connections per host: 250
    No TLS section defined
    No Plugin section defined
4 global component configuration(s):
- security/bot-detector
    patterns: [(Pingdom.com_bot_version_).* (facebookexternalhit)/.*]
    deny: [a b]
    allow: [c Pingdom.com_bot_version_1.1]
- security/cors
    expose_headers: [Content-Length]
    allow_methods: [POST GET]
    allow_origins: [*]
    allow_headers: [Origin Authorization Content-Type]
    max_age: 12h
- telemetry/logging
    level: DEBUG
    syslog: false
    stdout: true
    prefix: [KRAKEND]
- telemetry/metrics
    listen_address: :8090
    collection_time: 60s
1 API endpoints:
    - GET /example/:id
    Timeout: 3s
    QueryString: [q id]
    CacheTTL: 1h0m0s
    Headers to pass: [X-Header]
    OutputEncoding: json
    Concurrent calls: 1
    1 endpoint component configuration(s):
    - validation/cel
        [map[check_expr:'something' in req_headers['X-Header']] map[check_expr:int(req_params.Id) % 2 == 0]]
    Connecting to 2 backend(s):
        [+] GET /__debug/{{.Id}}
        Timeout: 3s
        Hosts: [http://127.0.0.1:8080]
        Concurrent calls: 1
        Host sanitization disabled: false
        Target:
        Deny: [], Allow: []
        Mapping: map[]
        Group: backend1
        Encoding:
        Is collection: false
        SD:
        1 backend component configuration(s):
        - validation/cel
            [map[check_expr:int(req_params.Id) % 3 == 0]]

        [+] GET /__debug/{{.Id}}
        Timeout: 3s
        Hosts: [http://127.0.0.1:8080]
        Concurrent calls: 1
        Host sanitization disabled: false
        Target:
        Deny: [], Allow: []
        Mapping: map[]
        Group: backend2
        Encoding:
        Is collection: false
        SD:
        1 backend component configuration(s):
        - validation/cel
            [map[check_expr:int(req_params.Id) % 5 == 0]]

1 async agent(s):
    - cool-agent
    Encoding:
    Consumer Timeout: 3s
    Consumer Workers: 20
    Consumer Topic: *.bar
    Consumer Max Rate: 0.000000
    Connection Max Retries: 10
    Connection Backoff Strategy: exponential-jitter
    Connection Health Interval: 1s
    1 agent component configuration(s):
    - github.com/devopsfaith/krakend-amqp/agent
        exchange: foo
        prefetch_count: 40
        auto_ack: true
        name: krakend
        host: amqp://guest:guest@localhost:5672/
    Connecting to 1 backend(s):
        [+] POST /__debug/cool-agent
        Timeout: 3s
        Hosts: [http://127.0.0.1:8080]
        Concurrent calls: 0
        Host sanitization disabled: false
        Target:
        Deny: [], Allow: []
        Mapping: map[]
        Group:
        Encoding:
        Is collection: false
        SD:
        0 backend component configuration(s):

Syntax OK!
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.

See all support channels