Decision

Decision is one of the operating modes supported by heimdall, used if you start heimdall with heimdall serve decision or heimdall serve decision --envoy-grpc. By default, heimdall listens on 0.0.0.0:4456/ endpoint for incoming requests in this mode of operation and also configures useful default timeouts. No other options are configured. You can, and should however adjust the configuration for your needs.

This service exposes only the Decision service endpoint.

Configuration

The configuration for the Decision service can be adjusted in the decision property, which lives in the serve property of heimdall’s configuration and supports the following properties.

  • host: string (optional)

    By making use of this property, you can specify the TCP/IP address on which heimdall should listen for connections from client applications. The entry 0.0.0.0 allows listening for all IPv4 addresses. 0.0.0.0 is also the default setting.

    Example 1. Configure heimdall to allow only local TCP/IP “loopback” connections to be made.

    Makes actually only sense, if your reverse proxy/gateway, which communicates with Heimdall, runs on the same machine.

    decision:
  host: 127.0.0.1

  • port: integer (optional)

    By making use of this property, you can specify the TCP port the heimdall should listen on. Defaults to 4456.

    Example 2. Configure heimdall’s decision service to listen on port 4444 for incoming requests.
    decision:
  port: 4444

  • timeout: Timeout (optional)

    Like written in the introduction of this section, Heimdall configures useful timeout defaults. You can however override this by making use of the timeout option and specifying the timeouts, you need.

    Example 3. Setting the read timeout to 1 second, write timeout to 2 seconds and the idle timeout to 1 minute.
    decision:
  timeout:
    read: 1s
    write: 2s
    idle: 1m

  • buffer_limit: BufferLimit (optional)

    Read and write buffer limits (defaults to 4KB) for incoming requests and responses created by heimdall. You can however override this by making use of this property and specifying the limits you need.

    Example 4. Setting the read buffer size limit to 1MB and the write buffer size limit to 2KB.
    decision:
  buffer_limit:
    read: 1MB
    write: 2KB

  • tls: TLS (optional)

    By default, the Decision service accepts HTTP requests. Depending on your deployment scenario, you could require Heimdall to accept HTTPs requests only (which is highly recommended). You can do so by making use of this option.

    Example 5. TLS configuration
    decision:
  tls:
    key_store:
      path: /path/to/keystore.pem
      password: VerySecure!

  • trusted_proxies: string array (optional)

    The usage of the Decision service makes only sense, if operated behind some sort of proxy, like API Gateway, etc. In such cases certain header information may be sent to Heimdall using e.g. special X-Forwarded-* headers or the Forwarded header. For example, the Host HTTP header is usually used to set the requested host. But when you’re behind a proxy, the actual host may be stored in an X-Forwarded-Host header, which could, however, also be spoofed.

    Depending on the integration options offered by those systems, which are used to integrate heimdall with, you may need to rely on the aforesaid headers. In such cases, you have to configure the trusted_proxies option and list the IPs, or IP ranges (CIDR notation) of your proxies, which integrate with heimdall. If not configured, heimdall will not accept those headers from any client to prevent spoofing as it might result in privilege escalation.

    Please consider security implications when making use of this property.
    Example 6. Enable the usage of the above said headers for only those requests, which came from the IPs listed in the configuration.
    decision:
  trusted_proxies:
    - 192.168.2.15
    - 192.168.2.16
    Example 7. Enable the usage of the above said headers for only those requests, which came from the network listed in the configuration.
    decision:
  trusted_proxies:
    - 192.168.2.0/24

  • respond: Respond (optional)

    By making use of this property you can instruct heimdall to preserve error information and provide it in the response body to the caller, as well as to use HTTP status codes deviating from those heimdall would usually use.

    Example 8. Configure verbose errors
    decision:
  respond:
    verbose: true
    Example 9. Use 404 Not Found for authentication and authorization errors
    decision:
  respond:
    with:
      authentication_error:
        code: 404
      authorization_error:
        code: 404

Last updated on Aug 7, 2023

Contour Integration
Proxy