Skip to main content

​
Main Configuration File

The krakend.json file is the main configuration file for KrakenD. It defines the API gateway’s behavior, endpoints, backends, and all integrations.

​
Location

The configuration file is located at: 
config/krakend/krakend.json

​
Auto-Reload Feature

When you change the krakend.json file in the playground, the changes are applied automatically without needing to restart the gateway.

​
Structure Overview

The main configuration file follows the KrakenD v3 schema and contains these top-level properties: 
{
  "$schema": "https://www.krakend.io/schema/v3.json",
  "version": 3,
  "name": "KrakenD Community API Gateway",
  "port": 8080,
  "host": ["http://fake_api"],
  "timeout": "3000ms",
  "cache_ttl": "300s",
  "endpoints": [...],
  "async_agent": [...],
  "extra_config": {...}
}

​
Key Properties

PropertyTypeDescription
versionnumberKrakenD configuration version (currently 3)
namestringDescriptive name for your gateway
portnumberPort where KrakenD listens (default: 8080)
hostarrayDefault backend hosts for endpoints
timeoutstringGlobal timeout for backend requests
cache_ttlstringDefault cache time-to-live for responses
endpointsarrayList of API endpoints exposed by the gateway
sequential_startbooleanWhether to start services sequentially
async_agentarrayConfiguration for async message consumers
extra_configobjectAdditional modules (CORS, logging, metrics, etc.)

​
Global Extra Config

The extra_config section at the root level configures gateway-wide features:

​
Security (CORS)

"security/cors": {
  "allow_origins": ["*"],
  "allow_methods": ["POST", "GET"],
  "allow_headers": ["Origin", "Authorization", "Content-Type"],
  "expose_headers": ["Content-Length"],
  "max_age": "12h"
}

​
Telemetry

The playground includes several telemetry integrations:
  • Metrics: Prometheus-compatible metrics on port 8090
  • Logging: Debug-level logging with custom prefix
  • Tracing: OpenCensus/Jaeger integration for distributed tracing
  • InfluxDB: Time-series metrics storage
  • GELF: Log forwarding to Logstash
"telemetry/metrics": {
  "collection_time": "30s",
  "listen_address": ":8090"
},
"telemetry/logging": {
  "level": "DEBUG",
  "prefix": "[KRAKEND]",
  "syslog": false,
  "stdout": true
}

​
Editing with KrakenD Designer

The easiest way to edit krakend.json is by using the KrakenD Designer:
  1. Drag and drop your krakend.json file to the Designer
  2. Make changes using the visual interface
  3. Download the edited file
  4. Replace config/krakend/krakend.json with the downloaded file
  5. The changes will be applied automatically

​
Basic Example

Here’s a minimal configuration example: 
{
  "$schema": "https://www.krakend.io/schema/v3.json",
  "version": 3,
  "name": "My API Gateway",
  "port": 8080,
  "timeout": "3000ms",
  "cache_ttl": "300s",
  "endpoints": [
    {
      "endpoint": "/public",
      "backend": [
        {
          "url_pattern": "/hotels/1.json"
        }
      ]
    }
  ]
}

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us