Deploying Lura

Introduction

Lura is the open-source framework behind KrakenD, a high-performance API Gateway designed for the modern microservices era. Written in Go, Lura enables you to aggregate multiple backend services into a single API, transform responses, and add cross-cutting concerns like authentication, rate limiting, and caching.

Unlike traditional API gateways that act as simple proxies, Lura takes a declarative, configuration-driven approach. Define your API endpoints in a JSON or YAML file, and Lura handles the complexity of orchestrating requests to multiple backends, merging responses, and applying transformations.

Key highlights of Lura:

• API Aggregation: Combine multiple backend calls into a single API response
• Response Transformation: Filter, rename, and restructure API responses
• High Performance: Handle thousands of requests per second with minimal latency
• Stateless Design: Horizontally scale without shared state or databases
• Configuration-Driven: No coding required; define everything in configuration
• Protocol Translation: Convert between REST, GraphQL, gRPC, and more
• Rate Limiting: Protect backends with configurable rate limits
• Circuit Breaker: Automatic failure handling with circuit breaker patterns
• Caching: Built-in response caching for improved performance
• Security: JWT validation, OAuth2, API keys, and more
• Observability: Metrics, tracing, and logging integration
• Open Source: Apache 2.0 licensed with active development

This guide walks through deploying Lura on Klutch.sh using Docker, configuring your API gateway, and managing your microservices endpoints.

Why Deploy Lura on Klutch.sh

Deploying Lura on Klutch.sh provides several advantages:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds Lura without complex configuration.

Persistent Storage: Attach persistent volumes for logs and configuration state.

HTTPS by Default: Klutch.sh provides automatic SSL certificates, ensuring secure API access.

GitHub Integration: Connect your configuration repository directly from GitHub for automated deployments.

Scalable Resources: Allocate CPU and memory based on expected API traffic.

Environment Variable Management: Securely store backend credentials through Klutch.sh’s environment variable system.

Custom Domains: Assign a custom domain to your API Gateway.

Always-On Availability: Your API gateway remains accessible 24/7.

Prerequisites

Before deploying Lura on Klutch.sh, ensure you have:

• A Klutch.sh account
• A GitHub account with a repository for your Lura configuration
• Basic familiarity with Docker and containerization concepts
• Understanding of API design and microservices architecture
• Backend services ready to be exposed through the gateway
• (Optional) A custom domain for your API gateway

Understanding Lura Architecture

Lura uses a streamlined, stateless architecture:

Gateway Core: The main Go binary that processes requests and applies configuration.

Configuration Parser: Reads the declarative configuration file at startup.

Backend Handlers: Components that call your backend services in parallel or sequentially.

Middleware Stack: Pluggable middleware for security, caching, rate limiting, etc.

Response Merger: Combines multiple backend responses into a single API response.

Router: High-performance HTTP router for incoming requests.

Preparing Your Repository

To deploy Lura on Klutch.sh, create a GitHub repository containing your configuration.

Repository Structure

lura-deploy/
├── Dockerfile
├── krakend.json
├── README.md
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in the root of your repository:

FROM devopsfaith/krakend:2.5

# Copy configuration
COPY krakend.json /etc/krakend/krakend.json

# Set environment variables
ENV KRAKEND_PORT=8080
ENV FC_ENABLE=1
ENV FC_SETTINGS=/etc/krakend/settings
ENV FC_PARTIALS=/etc/krakend/partials

# Expose gateway port
EXPOSE 8080

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=10s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:8080/__health || exit 1

CMD ["run", "-c", "/etc/krakend/krakend.json"]

Configuration File

Create a krakend.json configuration file:

{
  "$schema": "https://www.krakend.io/schema/v2.5/krakend.json",
  "version": 3,
  "name": "My API Gateway",
  "port": 8080,
  "timeout": "3000ms",
  "cache_ttl": "300s",
  "endpoints": [
    {
      "endpoint": "/api/users/{id}",
      "method": "GET",
      "output_encoding": "json",
      "backend": [
        {
          "url_pattern": "/users/{id}",
          "host": ["http://users-service:3000"],
          "encoding": "json"
        }
      ]
    },
    {
      "endpoint": "/api/products",
      "method": "GET",
      "output_encoding": "json",
      "backend": [
        {
          "url_pattern": "/products",
          "host": ["http://products-service:3000"],
          "encoding": "json",
          "mapping": {
            "items": "products"
          }
        }
      ]
    },
    {
      "endpoint": "/api/dashboard",
      "method": "GET",
      "output_encoding": "json",
      "backend": [
        {
          "url_pattern": "/user/profile",
          "host": ["http://users-service:3000"],
          "group": "user"
        },
        {
          "url_pattern": "/orders/recent",
          "host": ["http://orders-service:3000"],
          "group": "orders"
        },
        {
          "url_pattern": "/notifications/unread",
          "host": ["http://notifications-service:3000"],
          "group": "notifications"
        }
      ]
    }
  ],
  "extra_config": {
    "router": {
      "return_error_msg": true
    }
  }
}

Creating the .dockerignore File

Create a .dockerignore file:

.git
.github
*.md
LICENSE
.gitignore
*.log
.DS_Store
.env
.env.local

Environment Variables Reference

Variable	Required	Default	Description
KRAKEND_PORT	No	8080	Gateway listening port
FC_ENABLE	No	0	Enable flexible configuration
FC_SETTINGS	No	-	Path to settings directory
FC_PARTIALS	No	-	Path to partial configs

Deploying Lura on Klutch.sh

Once your repository is prepared, follow these steps to deploy:

Push Your Repository to GitHub

Initialize your repository and push to GitHub:

git init
git add Dockerfile krakend.json .dockerignore README.md
git commit -m "Initial Lura API Gateway deployment"
git remote add origin https://github.com/yourusername/lura-deploy.git
git push -u origin main

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project. Give it a descriptive name like “lura-gateway” or “api-gateway”.

Create a New App

Within your project, create a new app. Connect your GitHub account if you haven’t already, then select the repository containing your Lura Dockerfile.

Configure HTTP Traffic

In the deployment settings:

• Select HTTP as the traffic type
• Set the internal port to 8080

Set Environment Variables

In the environment variables section, add:

Variable	Value
KRAKEND_PORT	8080
FC_ENABLE	1

Attach Persistent Volumes

Add the following volumes:

Mount Path	Recommended Size	Purpose
/var/log/krakend	1 GB	Gateway access and error logs

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will:

• Detect your Dockerfile automatically
• Build the container image
• Attach the persistent volumes
• Start the Lura container
• Provision an HTTPS certificate

Access Your API Gateway

Once deployment completes, your API gateway is available at https://example-app.klutch.sh.

Configuring API Endpoints

Basic Endpoint

Define a simple proxy endpoint:

{
  "endpoint": "/api/users",
  "method": "GET",
  "backend": [
    {
      "url_pattern": "/users",
      "host": ["http://backend:3000"]
    }
  ]
}

Response Aggregation

Combine multiple backends:

{
  "endpoint": "/api/profile",
  "backend": [
    {
      "url_pattern": "/user",
      "host": ["http://users:3000"],
      "group": "user"
    },
    {
      "url_pattern": "/preferences",
      "host": ["http://settings:3000"],
      "group": "preferences"
    }
  ]
}

Response Filtering

Return only specific fields:

{
  "endpoint": "/api/user/{id}",
  "backend": [
    {
      "url_pattern": "/users/{id}",
      "host": ["http://users:3000"],
      "allow": ["id", "name", "email"]
    }
  ]
}

Rate Limiting

Add rate limiting to endpoints:

{
  "endpoint": "/api/public",
  "extra_config": {
    "qos/ratelimit/router": {
      "max_rate": 100,
      "client_max_rate": 10,
      "strategy": "ip"
    }
  },
  "backend": [...]
}

JWT Authentication

Protect endpoints with JWT:

{
  "endpoint": "/api/protected",
  "extra_config": {
    "auth/validator": {
      "alg": "RS256",
      "jwk_url": "https://auth.example.com/.well-known/jwks.json",
      "roles_key": "roles",
      "roles": ["admin", "user"]
    }
  },
  "backend": [...]
}

Advanced Configuration

Circuit Breaker

Protect backends from cascading failures:

{
  "backend": [
    {
      "url_pattern": "/service",
      "host": ["http://backend:3000"],
      "extra_config": {
        "qos/circuit-breaker": {
          "interval": 60,
          "timeout": 10,
          "max_errors": 5
        }
      }
    }
  ]
}

Response Caching

Cache backend responses:

{
  "backend": [
    {
      "url_pattern": "/products",
      "host": ["http://catalog:3000"],
      "extra_config": {
        "qos/http-cache": {
          "shared": true
        }
      }
    }
  ]
}

Request/Response Transformation

Modify requests and responses:

{
  "backend": [
    {
      "url_pattern": "/legacy",
      "host": ["http://legacy:3000"],
      "mapping": {
        "old_field": "new_field"
      },
      "deny": ["internal_id", "secret"]
    }
  ]
}

Production Best Practices

Security Recommendations

• TLS Termination: Use HTTPS for all client connections
• JWT Validation: Validate tokens at the gateway level
• CORS Configuration: Properly configure CORS policies
• Input Validation: Validate request parameters
• Rate Limiting: Protect backends from abuse

Performance Optimization

• Connection Pooling: Configure backend connection pools
• Response Caching: Cache frequently accessed responses
• Timeout Tuning: Set appropriate timeouts for each backend
• Concurrent Requests: Tune concurrency limits
• Compression: Enable response compression

Monitoring

Monitor your API gateway:

1. Metrics Export: Enable Prometheus metrics
2. Distributed Tracing: Integrate with Jaeger or Zipkin
3. Access Logging: Log all requests for analysis
4. Error Tracking: Monitor error rates and types

Troubleshooting Common Issues

Backend Connection Failures

Symptoms: Gateway returns 502 or 503 errors.

Solutions:

• Verify backend service is running
• Check network connectivity to backends
• Review backend URL patterns
• Check timeout configuration

Configuration Validation Errors

Symptoms: Gateway fails to start.

Solutions:

• Validate JSON syntax
• Check against the JSON schema
• Use the KrakenD Designer for visual validation
• Review startup logs for specific errors

Slow Response Times

Symptoms: API responses are slower than expected.

Solutions:

• Enable caching for appropriate endpoints
• Check backend response times
• Review aggregation patterns
• Consider response filtering to reduce payload size

Additional Resources

• Lura Project Website
• KrakenD Documentation
• Lura GitHub Repository
• KrakenD Designer
• Klutch.sh Persistent Volumes
• Klutch.sh Deployments

Conclusion

Deploying Lura on Klutch.sh gives you a powerful, high-performance API Gateway for managing your microservices. The combination of Lura’s declarative configuration and Klutch.sh’s deployment simplicity means you can focus on your API design rather than infrastructure.

With API aggregation, response transformation, and built-in security features, Lura handles the complexity of orchestrating microservices behind a clean, unified API. Whether you’re building a new API layer or modernizing legacy services, Lura on Klutch.sh provides the reliable, scalable foundation you need.