Configuration Introduction

Configuration in Heimdall can refer to two different things:

The fully dynamic configuration of rules - the rule set
The static startup configuration

Elements in the static configuration set up the services, like decision api, which basically define the entrypoints, Heimdall will listen to, the observability capabilities, like logging, the supported pipeline mechanisms, the default rule, as well as the rule providers (these elements are not expected to change often).

The rule set contains everything that defines how the requests are handled by Heimdall for your system. This configuration can change and is seamlessly hot-reloaded, without any request interruption or connection loss.

Rule Set Configuration

Heimdall gets the rule sets from rule providers, which, depending on the provider, can load rules from a plain old configuration file, residing in the local file system, or even integrate with Kubernets to load rules from CRDs.

In all cases, a single rule definition adheres to the schema defined in rule configuration.

Static Configuration

There are two different, not mutually exclusive (you can combine them), ways to define static configuration options in Heimdall:

in a configuration file (only YAML is supported as format)
as environment variables

The evaluation happens also in the order stated above. That also means, you can always overwrite configuration options defined in a configuration file with corresponding environment variables.

If no configuration is provided, heimdall will set useful defaults. These are however not enough, as heimdall doesn’t know your context - which mechanisms are required for the one or the other of your upstream endpoints. So, you’ll not really be able to use heimdall as all requests will be answered with an HTTP 404 Not Found response code.

Configuration File

At start up, Heimdall searches for static configuration in a file named heimdall.yaml in

/etc/heimdall
$HOME/.config
the current working directory

You can also override this using the config argument: heimdall --config <path-to-your-config-file>.

Example 1. Possible minimal fully working configuration

The configuration below defines a default rule which lets Heimdall create a JSON Web Token (JWT) with sub claim set to anonymous for every request on every URL for the HTTP methods GET and POST. The JWT itself will be put into the Authorization header as a bearer token.

log:
  level: info

pipeline:
  authenticators:
    - id: anonymous_authenticator
      type: anonymous
  mutators:
    - id: create_jwt
      type: jwt

rules:
  default:
    methods:
      - GET
      - POST
    execute:
      - authenticator: anonymous_authenticator
      - mutator: create_jwt

Environment Variables

Every configuration property, which can be defined in a configuration file can also be defined as environment variable. Following rules apply:

If not specified while starting heimdall, all variables start with HEIMDALLCFG_ prefix.

If for whatever reason, your environment configuration contains variables starting with HEIMDALLCFG_, which do not define heimdall specific configuration, heimdall will refuse starting if such configuration variable clashes (has an unexpected type) with heimdall’s configuration properties (even for environment variables, the configuration is type safe). You can overcome such situation, by ether renaming such variables, or, if this is not possible, make use of the --env-config-prefix flag with heimdall’s serve command.

Properties in a hierarchy are separated by _
E.g. the log level can be set to info in a config file as also shown in the above example with
```
log:
  level: info
```
and using an environment variable with
```
HEIMDALLCFG_LOG_LEVEL=info
```
Array entries must be defined using _<IDX>[_], with IDX being the index of the array starting with 0 and _ in brackets being only required, if the value of the configured element has a structure/hierarchy.
E.g. the methods of the default rule can be configured in a config file as
```
rules:
  default:
    methods:
      - GET
      - POST
```
and using environment variables with
```
HEIMDALLCFG_RULES_DEFAULT_METHODS_0=GET
HEIMDALLCFG_RULES_DEFAULT_METHODS_1=POST
```
For structured configuration, like the definition of the authenticators in the example above
```
pipeline:
  authenticators:
    - id: anonymous_authenticator
      type: anonymous
```
The corresponding environment variables would be
```
HEIMDALLCFG_PIPELINE_AUTHENTICATORS_0_ID=anonymous_authenticator
HEIMDALLCFG_PIPELINE_AUTHENTICATORS_0_TYPE=anonymous
```
If a name of a property has _ it must be escaped with an additional _.
E.g. the service name, appearing for Heimdall for your tracing backend can be configured in a configuration file with
```
tracing:
  service_name: foobar
```
and using the environment variables with
```
HEIMDALLCFG_TRACING_SERVICE__NAME=foobar
```

Last updated on Sep 2, 2022

Proxy Quickstart

Install