Caching

To increase performance, you can configure heimdall to make use of caching. Indeed, caching is even done by default in some places.

Even some default caching is in place, and you can instruct heimdall to cache particular data for some amount of time, like e.g how long to cache the response from the JWKS endpoint when using the JWT Authenticator, all these options require a caching backend to be available. Otherwise, the corresponding configurations do not have any effect.

Configuration of that backend happens by making use of the cache property in heimdall’s configuration, which supports the following options:

  • type - The mandatory specific type of the cache backend.

  • config - A cache backend specific configuration if required by the type.

Noop Backend

With that backend configured, caching is disabled entirely. That means any cache settings on any mechanism do not have any effect. Even those, applied by heimdall by default are disabled.

To configure this backend, you have to specify noop as type. No further configuration is supported. Here an example:

cache:
  type: noop

In-Memory Backend

This is the default caching backend used by heimdall. It manages the cached items in memory of heimdall’s process. To explicitly configure it, specify in-memory as the type.

cache:
  type: in-memory

Additional optional configuration options via config allow control over the cache’s memory usage (defaulting to 128MB if not specified) and the number of entries it can hold. The following properties are supported:

  • memory_limit: ByteSize (optional)

    The maximum amount of memory the cache is allowed to use. This limit helps prevent excessive memory consumption and may affect the number of entries stored. Defaults to 128MB.

  • entry_limit: integer (optional)

    The maximum number of entries the cache can store. This limit ensures the cache doesn’t grow indefinitely and can be used in conjunction with memory_limit to manage cache size. If not specified, there is no limit on the number of entries.

Here is an example configuration that sets the memory limit to 256MB and the entry limit to 10000:

cache:
  type: in-memory
  config:
    memory_limit: 256MB
    entry_limit: 10000

Redis Backends

As the name of this chapter implies, there are multiple backend types, you can configure to make use of Redis as distributed cache:

All types use pipelining to increase performance and do also make use of client side caching if not disabled (see also below).

Common Settings

All Redis cache backend types support the following configuration options:

  • credentials: Credentials (optional)

    Herewith you can define the credentials to be used for connection purposes. Following settings are possible

    • path: string (mandatory)

      Path to a JSON/YAML file with credentials (supports watching for secrets rotation) specifying the username and password as shown below.

      # contents of a credentials file
username: Aladdin
password: SesameOpen!

      If used no other properties can be configured for credentials.

    • username: string(optional)

      The username to use to connect to the Redis DB/Cluster, and

    • password: string(mandatory)

      The password to be used

  • client_cache: ClientCache (optional)

    Configures the client cache to reduce roundtrip time. Following settings are possible:

    • disabled: boolean (optional)

      Whether the client cache should be disabled. Defaults to false.

    • ttl: Duration (optional)

      Specifies the maximum TTL on the client side for all used keys. If the key’s TTL on the server is smaller than the client side TTL, the client side TTL will be capped.

    • size_per_connection: ByteSize (optional)

      Client side cache size that bind to each TCP connection to a single redis instance. Defaults to 128MB.

  • buffer_limit: BufferLimit (optional)

    Read and write buffer limits for established connections. Following configuration properties are supported:

    • read: ByteSize (optional)

      The maximum size for the read buffer allowed to read the full request including body. Defaults to 0.5MB.

    • write: ByteSize (optional)

      The maximum size for the write buffer of the response. Defaults to 0.5MB.

  • timeout: Timeout (optional)

    By using this property you can override the default connection timeouts. Following properties are supported:

    • write: Duration (optional)

      The maximum duration before timing out writes of the response. Defaults to 150s.

  • max_flush_delay: Duration (optional)

    Data flush delay. When greater than zero, pauses pipeline write loop for some time (not larger than the specified delay) after each flushing of data to the connection. This gives pipeline a chance to collect more commands to send to Redis. Adding this delay increases latency, reduces throughput, but in most cases may significantly reduce application and Redis CPU utilization due to less executed system calls. By default, the data is flushed to the connection without extra delays. Depending on network latency and application-specific conditions the value of max_flush_delay may vary, something like 20 µs should not affect latency/throughput a lot but still produce notable CPU usage reduction under load. Defaults to 0s.

  • tls: TLS (optional)

    TLS settings. By default, the communication to Redis happens over TLS. This requires however a properly configured trust store, as otherwise heimdall won’t trust the certificates used by the Redis services. In addition to the referenced configuration options, you can also make use of the following properties:

    • disabled: boolean (optional)

      Disables TLS. Defaults to false.

      This property can be set to true only if heimdall is started with the --insecure-skip-egress-tls-enforcement flag, which allows insecure communication with any configured service.

Redis Single Instance

As the name implies, this type supports configuration of a single instance Redis DB.

To use it, you have to specify redis as type. Configuration is mandatory with following options in addition to the configuration options described in Common Settings.

  • address: string (mandatory)

    The Redis instance address to connect to.

  • db: integer (optional)

    Redis DB ID to use. Defaults to 0.

Here an example:

cache:
  type: redis
  config:
    address: foo:12345
    credentials:
      path: /path/to/credentials.yaml
    client_cache:
      ttl: 10m
      size_per_connection: 128MB
    buffer_limit:
      read: 1MB
      write: 1MB
    timeout:
      write: 150s
    max_flush_delay: 20us
    tls:
      # TLS client auth is used here
      key_store:
        path: /path/to/keystore/file.pem
        password: ${MY_REDIS_CLIENT_KEYSTORE}
      min_version: TLS1.2

Redis Cluster

As the name implies, this type supports configuration of a Redis cluster.

To use it, you have to specify redis-cluster as type. Configuration is mandatory with following options in addition to the configuration options described in Common Settings.

  • nodes: array of strings (mandatory)

    The addresses of Redis nodes to connect to.

Here an example:

cache:
  type: redis-cluster
  config:
    nodes:
    - foo:1234
    - bar:1234
    credentials:
      username: ${MY_REDIS_USER}
      password: ${MY_REDIS_PASSWORD}

Redis Sentinel

As the name implies, this type supports configuration of a Redis sentinel.

To use it, you have to specify redis-sentinel as type. Configuration is mandatory with following options in addition to the configuration options described in Common Settings.

  • nodes: array of strings (mandatory)

    The addresses of Redis sentinel nodes to connect to.

  • db: integer (optional)

    Redis DB ID to use. Defaults to 0.

  • master: string (mandatory)

    Sentinel master set name

Same credentials are used to connect to the sentinel service and to the Redis DB instances. This is also true if TLS client authentication is used.

Here an example:

cache:
  type: redis-sentinel
  config:
    nodes:
    - foo:1234
    - bar:1234
    db: 0
    master: whatever
    credentials:
      path: /path/to/credentials.yaml

Last updated on Mar 27, 2025

Observability Security