Flexible Configuration: A template-based config for API Gateway

Document updated on Aug 22, 2023

The Flexible Configuration allows you to declare the configuration using multiple files and use a templates system, opening the door to multi-environment configurations and code reuse.

The Flexible Configuration enables a template processor based on Go templates and is enriched with Sprig functions and KrakenD functions.

You can encode your configuration files in any of the supported formats (json, yaml, toml, etc.), as the template is agnostic of its contents.

Use the Flexible Configuration when you need to:

• Split an extensive configuration into several files
• Inject variables, like environment settings, into the configuration
• Use placeholders and reusable code blocks to avoid repeating code
• Organize your code better when multiple developers are modifying the gateway
• Manage KrakenD using multiple repositories (and merging the files in the CI)
• Track changes, avoid conflicts, and review code more easily
• Have the full power of a template system!

How it works

Activating the Flexible Configuration requires injecting at least the environment variable FC_ENABLE=1 when running a krakend run or check command and additional variables depending on the features you’d like to enable.

When you enable through the environment variables this feature, the configuration is loaded internally into a template parser that collects all the involved files and renders the final configuration file.

Flexible Configuration variables

The environment variables of the flexible configuration are:

• FC_ENABLE=1: Activates Flexible Configuration. You can use 1 or any other value (but 0 won’t turn it off!). The file passed with the --config flag is the base template and contains the references to any other templates.
• FC_TEMPLATES=path/to/templates: The path to the templates directory. These are evaluated using the Go templating system.
• FC_SETTINGS=path/to/settings: The path to the settings directory. Settings are JSON files that you can use to fill values in the templates, much similar to env files in other applications, but richer as you can use multiple files, structures, and nesting.
• FC_PARTIALS=path/to/partials: The path to the partials directory. Partial files are pieces of text that DON’T EVALUATE, and they are inserted in the placeholder “as is”.
• FC_OUT=file.json: Saves the resulting configuration after rendering the template, useful for debugging, not required for runtime.

For instance, let’s write a simple template simple.tmpl (go template emulating a json format):

{
    "version": {{add 2 1}}
}

If the template system works, the server will start with a value "version": 3. We can test it with (Docker example):

$docker run --rm -v "$PWD:/etc/krakend/" -e "FC_ENABLE=1" -e "FC_OUT=result.json" devopsfaith/krakend check -c simple.tmpl
Parsing configuration file: simple.tmpl
Syntax OK!

We know that it works because KrakenD will fail with a different version value, but we can also check the contents of result.json for debugging purposes.

Let’s now introduce the rest of the optional variables. For instance, let’s assume you decided to organize your code as follows:

.
├── krakend.tmpl
└── config
    ├── partials
    │   └── file.txt
    ├── templates
    │   ├── telemetry.tmpl
    │   └── endpoints.tmpl
    └── settings
        ├── prod
        |   └── urls.json
        └── dev
            └── urls.json

Then you could run KrakenD from the terminal with this command:

$FC_ENABLE=1 \
FC_SETTINGS="config/settings/prod" \
FC_PARTIALS="config/partials" \
FC_TEMPLATES="config/templates" \
FC_OUT="output.json" \
krakend run -c "krakend.tmpl"

In the example above, notice that the FC_SETTINGS includes the path to the production folder. This is how you would set a specific environment. You might inject here an env var if you have multiple environments. The directory structure is completely up to you.

Template syntax

The configuration file passed with the -c flag is treated as a Go template, and you can use all the power the template engine brings. In addition, the templating system is overloaded with Sprig functions, and KrakenD functions, adding more features.

The data evaluations or control structures are easily recognized as they are surrounded by {{ and }}. Any other text outside these delimiters is unprocessed text copied to the output as it is.

Read the Flexible Config Templates documentation to start playing with templates.

Testing the configuration

We recommend using a Docker compose file to work faster with flexible configuration.

Save the following docker-compose.yml and do a docker-compose up. This setup with the :watch image will allow you to work locally with the latest version of KrakenD and apply the changes automatically whenever you change a source file.

version: "3"
services:
  krakend:
    image: devopsfaith/krakend:watch
    volumes:
      - "./:/etc/krakend/"
    environment:
      - FC_ENABLE=1
      - FC_OUT=/etc/krakend/out.json
      - FC_PARTIALS=/etc/krakend/config/partials
      - FC_SETTINGS=/etc/krakend/config/settings/test
      - FC_TEMPLATES=/etc/krakend/config/templates
    command: ["run","-dc","krakend.tmpl"]

As the flexible configuration is composed of several pieces, it’s easy to make a mistake at some point. Test the syntax of all the files with the krakend check command and pay attention to the output to verify there aren’t any errors. When there are errors, the output contains information to help you resolve it, e.g.:

ERROR parsing the configuration file: loading flexible-config settings:
- backends.json: invalid character '}' looking for beginning of object key string

The variable FC_OUT writes the content of the final file in a known path, so you can check its contents at any time.

If you don’t use docker-compose, you can also use flexible configuration as follows:

$FC_ENABLE=1 \
FC_SETTINGS="$PWD/config/settings" \
FC_PARTIALS="$PWD/config/partials" \
FC_TEMPLATES="$PWD/config/templates" \
FC_OUT=out.json \
krakend check -t -d -c "$PWD/config/krakend.json"

Improve this page