KrakenD Community Edition

KrakenD is a high-performance API Gateway designed for microservices and Backend For Frontend (BFF) implementations. Key technical capabilities include:

• Content Management: Aggregation, composition, filtering, and format transformation (e.g., XML to JSON).
• Security: Support for Zero-trust, CORS, OAuth, JWT, HSTS, and various XSS/MIME-Sniffing protections.
• Traffic Control: Throttling, multi-layer rate-limiting (including bursting and circuit breakers), and concurrent backend calls.
• Observability: Telemetry integration with Datadog, Zipkin, Jaeger, Prometheus, and Grafana.
• Extensibility: Support for Go plugins, Lua scripts, Martian, and Google CEL spec.
• Protocols: SSL and HTTP2 ready.

If you want to build the KrakenD binary yourself, you can use the provided Makefile.

Ensure you have the correct Go version installed as specified in the Makefile. If you do not have Go installed locally, you can use the Docker-based build command which utilizes a Go container to perform the compilation.

The fastest way to start KrakenD is by using the official Docker image. By default, it listens on port 8080. You can verify the gateway is running by checking the /__health endpoint.

To use your own configuration, you must replace the default /etc/krakend/krakend.json file inside the container with your custom configuration file (which can be generated using the KrakenD Designer).

docker run -it -p "8080:8080" krakend

You can customize the JSON response returned when a route is not found (404) or a method is not allowed (405) by adding an error_body to the ExtraConfig under the luragin namespace.

The configuration structure follows this JSON pattern:

{
  "extra_config": {
    "luragin": {
      "error_body": {
        "404": { "error": "Not Found", "status": 404 },
        "405": { "error": "Method Not Allowed", "status": 405 }
      }
    }
  }
}

KrakenD CE supports flexibleconfig for advanced configuration management using templates, partials, and settings. To enable this mode, you must set the FC_ENABLE environment variable. When enabled, the following environment variables control the flexible configuration behavior:

• FC_ENABLE: Enables flexible configuration.
• FC_PARTIALS: Path to partial configuration files.
• FC_TEMPLATES: Path to configuration templates.
• FC_SETTINGS: Path to settings files.
• FC_OUT: The output path for the processed configuration.

Use NewHandlerFactory to create a router.HandlerFactory that comes pre-configured with a standard middleware stack. The stack includes:

• Rate limiting (ratelimit)
• Lua scripting support (lua)
• JOSE/JWT rejection (ginjose)
• Metrics collection (metrics)
• OpenCensus instrumentation (opencensus)
• Bot detection (botdetector)

To use the resulting factory, call it with an *config.EndpointConfig and a proxy.Proxy to obtain a gin.HandlerFunc for your endpoints.

Use NewBackendFactory to create a proxy.BackendFactory that automatically stacks all available KrakenD middlewares. This includes OAuth2 client credentials, HTTP cache, Martian, PubSub, AMQP, CEL, Lua, Rate-limiting, Circuit Breaker, and various metrics collectors (Metrics and OpenCensus).

This function uses context.Background() internally.

Implement MetricsAndTracesRegister to define how metrics and traces are collected and exported. The default implementation (MetricsAndTraces) supports:

• InfluxDB: For metric storage.
• OpenCensus: For distributed tracing.
• OpenTelemetry (OTel): For modern observability exporters.

Note: The MetricsAndTraces implementation implements io.Closer to ensure telemetry resources are cleaned up during shutdown.

Implement the LoggerFactory interface to control how KrakenD initializes its logging system. The default LoggerBuilder implementation attempts to set up logging in the following order of precedence:

1. GELF: If configured in ExtraConfig.
2. Logstash: If configured in ExtraConfig.
3. Gologging: Standard structured logging.
4. Stdout: Fallback to basic debugging output.

Use NewEngine to create a new Gin engine instance pre-configured with KrakenD defaults. This function automatically sets up:

• Default handlers for NoRoute (404) and NoMethod (405).
• Custom error bodies if defined in cfg.ExtraConfig under the luragin namespace.
• httpsecure middleware registration.
• lua router integration.
• botdetector middleware registration.

To customize the error response for 404 or 405 errors, provide an error_body object in your ExtraConfig using the luragin namespace.

import (
	"github.com/gin-gonic/gin"
	"github.com/luraproject/lura/v2/config"
	"github.com/luraproject/lura/v2/router/gin"
)

// Example usage pattern
engine := krakend.NewEngine(cfg, opt)

Use NewProxyFactory to create a proxy.Factory that includes the default KrakenD proxy stack. This factory automatically wraps the provided BackendFactory with several middleware layers, including:

• JSON Schema validation (jsonschema)
• Common Expression Language (cel)
• Lua scripting (lua)
• Metrics collection (metrics)
• OpenCensus instrumentation (opencensus)

The returned factory is a proxy.FactoryFunc that, when called with an *config.EndpointConfig, builds a proxy.Proxy for that specific endpoint.