Environment Settings

Environment settings allow you to maintain different configurations for development, staging, and production environments using the same template files.

Settings Directory Structure

Environment-specific variables are stored in separate directories:

config/krakend/settings/
├── dev/
│   └── env.json
└── prod/
    └── env.json

Each environment has its own env.json file containing environment-specific values.

Development Environment

The development environment uses local service names suitable for Docker Compose or local development.

settings/dev/env.json

{
  "port": 8080,
  "host_member": "http://member",
  "host_logistics": "http://logistics",
  "host_payment": "http://payment",
  "host_order": "http://order",
  "host_case": "http://case",
  "host_channel": "http://channel",
  "host_ticket": "http://ticket",
  "security": "https://keycloak/auth/realms/default/protocol/openid-connect/certs",
  "name": "DEV"
}

Key Features

Local hosts: Service names (e.g., http://member) resolve via Docker Compose
Port: Standard port 8080 for local development
Keycloak: Local Keycloak instance for authentication
Name: Environment identifier “DEV”

Production Environment

The production environment uses fully qualified domain names (FQDNs) for production services.

settings/prod/env.json

{
  "port": 8080,
  "host_member": "http://member.production-host.com",
  "host_logistics": "http://logistics.production-host.com",
  "host_payment": "http://payment.production-host.com",
  "host_order": "http://order.production-host.com",
  "host_case": "http://case.production-host.com",
  "host_channel": "http://channel.production-host.com",
  "host_ticket": "http://ticket.production-host.com",
  "security": "https://keycloak/auth/realms/default/protocol/openid-connect/certs",
  "name": "PROD"
}

Key Features

Production hosts: Full domain names (e.g., http://member.production-host.com)
Port: Same port 8080 (typically behind a load balancer)
Keycloak: Production Keycloak instance
Name: Environment identifier “PROD”

Environment Variables Structure

The env.json file typically contains:

Common Variables

Variable	Type	Description
`port`	number	KrakenD listening port
`name`	string	Environment name (DEV, STAGING, PROD)
`security`	string	JWT validation endpoint URL

Service Hosts

Define backend service URLs:

{
  "host_member": "http://member-service",
  "host_logistics": "http://logistics-service",
  "host_payment": "http://payment-service"
}

Using in Templates

Access variables in your template files:

{
  "endpoint": "/members/{id}",
  "backend": [
    {
      "host": ["{{ .env.host_member }}"],
      "url_pattern": "/api/members/{id}"
    }
  ]
}

Switching Environments

There are several ways to switch between environments:

Method 1: Environment Variable

Set the FC_SETTINGS environment variable to specify which settings directory to use:

# Use development settings
export FC_SETTINGS="settings/dev"
krakend run -c krakend-flexible-config.tmpl

# Use production settings
export FC_SETTINGS="settings/prod"
krakend run -c krakend-flexible-config.tmpl

Method 2: Inline Environment Variable

Specify the environment when starting KrakenD:

FC_SETTINGS="settings/prod" krakend run -c krakend-flexible-config.tmpl

Method 3: Docker Compose

In your docker-compose.yml:

services:
  krakend:
    image: devopsfaith/krakend:latest
    environment:
      - FC_ENABLE=1
      - FC_SETTINGS=settings/dev
    volumes:
      - ./config/krakend:/etc/krakend

Method 4: CI/CD Pipeline

In your deployment pipeline:

# Development deployment
docker run -e FC_SETTINGS="settings/dev" krakend:latest

# Production deployment
docker run -e FC_SETTINGS="settings/prod" krakend:latest

Adding New Environments

To add a staging environment:

Create the settings directory:

mkdir -p config/krakend/settings/staging

Create env.json with staging-specific values:

{
  "port": 8080,
  "host_member": "http://member.staging-host.com",
  "host_logistics": "http://logistics.staging-host.com",
  "host_payment": "http://payment.staging-host.com",
  "security": "https://keycloak-staging/auth/realms/default/protocol/openid-connect/certs",
  "name": "STAGING"
}

Use it:

FC_SETTINGS="settings/staging" krakend run -c krakend-flexible-config.tmpl

Environment-Specific Configuration

Timeouts

Adjust timeouts based on environment:

{
  "dev": {
    "timeout": "30s"
  },
  "prod": {
    "timeout": "5s"
  }
}

In template:

"timeout": "{{ .env.timeout }}"

Feature Flags

Enable/disable features per environment:

{
  "enable_debug": true,
  "enable_cache": false,
  "enable_rate_limit": false
}

In template:

{{ if .env.enable_rate_limit }}
"extra_config": {
  "qos/ratelimit/router": {
    "max_rate": 100
  }
}
{{ end }}

Logging Levels

{
  "dev": {"log_level": "DEBUG"},
  "prod": {"log_level": "WARNING"}
}

Best Practices

1. Never Commit Secrets

Don’t store secrets in env.json files committed to version control. Use:

Environment variables for secrets
Secret management tools (Vault, AWS Secrets Manager)
.gitignore for local environment files

2. Validate Environment Files

Ensure all required variables are present in each environment:

# Check if env.json is valid JSON
jq empty settings/dev/env.json
jq empty settings/prod/env.json

3. Document Required Variables

Maintain a README or schema documenting required variables:

## Required Variables

- `port`: KrakenD port (number)
- `host_*`: Backend service URLs (string)
- `security`: JWT validation endpoint (string)
- `name`: Environment name (string)

4. Use Descriptive Names

Use clear, descriptive variable names:

// Good
{
  "host_member_service": "http://members.prod.com",
  "jwt_validation_url": "https://auth.prod.com/certs"
}

// Avoid
{
  "h1": "http://members.prod.com",
  "url": "https://auth.prod.com/certs"
}

5. Keep Parity Between Environments

All environment files should have the same structure:

# Use a schema validator
jsonschema -i settings/dev/env.json schema.json
jsonschema -i settings/prod/env.json schema.json

Testing Configuration

Compile and Check

Before deploying, compile and validate your configuration:

# Compile development config
FC_SETTINGS="settings/dev" krakend check -t -c krakend-flexible-config.tmpl

# Compile production config
FC_SETTINGS="settings/prod" krakend check -t -c krakend-flexible-config.tmpl

Compare Environments

Generate and compare configurations:

# Generate dev config
FC_SETTINGS="settings/dev" krakend check -t -c krakend-flexible-config.tmpl > config-dev.json

# Generate prod config
FC_SETTINGS="settings/prod" krakend check -t -c krakend-flexible-config.tmpl > config-prod.json

# Compare
diff config-dev.json config-prod.json

Next Steps

Learn about flexible configuration templates
View endpoint configuration examples
Explore the main configuration file structure

Get Started

Services

Features & Examples

Configuration

Operations

Environment Settings

Environment Settings

Settings Directory Structure

Development Environment

settings/dev/env.json

Key Features

Production Environment

settings/prod/env.json

Key Features

Environment Variables Structure

Common Variables

Service Hosts

Using in Templates

Switching Environments

Method 1: Environment Variable

Method 2: Inline Environment Variable

Method 3: Docker Compose

Method 4: CI/CD Pipeline

Adding New Environments

Environment-Specific Configuration

Timeouts

Feature Flags

Logging Levels

Best Practices

1. Never Commit Secrets

2. Validate Environment Files

3. Document Required Variables

4. Use Descriptive Names

5. Keep Parity Between Environments

Testing Configuration

Compile and Check

Compare Environments

Next Steps

Build docs developers (and LLMs) love

Get Started

Services

Features & Examples

Configuration

Operations

​Environment Settings

​Settings Directory Structure

​Development Environment

​settings/dev/env.json

​Key Features

​Production Environment

​settings/prod/env.json

​Key Features

​Environment Variables Structure

​Common Variables

​Service Hosts

​Using in Templates

​Switching Environments

​Method 1: Environment Variable

​Method 2: Inline Environment Variable

​Method 3: Docker Compose

​Method 4: CI/CD Pipeline

​Adding New Environments

​Environment-Specific Configuration

​Timeouts

​Feature Flags

​Logging Levels

​Best Practices

​1. Never Commit Secrets

​2. Validate Environment Files

​3. Document Required Variables

​4. Use Descriptive Names

​5. Keep Parity Between Environments

​Testing Configuration

​Compile and Check

​Compare Environments

​Next Steps

Build docs developers (and LLMs) love

Environment Settings

Settings Directory Structure

Development Environment

settings/dev/env.json

Key Features

Production Environment

settings/prod/env.json

Key Features

Environment Variables Structure

Common Variables

Service Hosts

Using in Templates

Switching Environments

Method 1: Environment Variable

Method 2: Inline Environment Variable

Method 3: Docker Compose

Method 4: CI/CD Pipeline

Adding New Environments

Environment-Specific Configuration

Timeouts

Feature Flags

Logging Levels

Best Practices

1. Never Commit Secrets

2. Validate Environment Files

3. Document Required Variables

4. Use Descriptive Names

5. Keep Parity Between Environments

Testing Configuration

Compile and Check

Compare Environments

Next Steps