Emissary Ingress Integration

This guide explains how to integrate heimdall with Emissary-Ingress Controller.

Emissary-Ingress is an Envoy-powered open source, high performance ingress controller and API Gateway for Kubernetes from Ambassador Labs. Integration happens by letting Emissary-Ingress delegating authentication and authorization to heimdall. If heimdall answers with a 2XX code, the ingress controller will grant access and forwards the original request to the upstream service. Otherwise, the response from heimdall is returned to the client.

Prerequisites

Integration with Emissary-Ingress requires heimdall being operated in Decision Operation Mode.

Global Configuration

Integration with Emissary-Ingress can be achieved either

by creating an AuthService resource for heimdall, or
by creating an External Filter if you’re using the commercial Ambassador Edge Stack.

In both cases the underlying Envoy proxy will be configured to delegate authentication and authorization of all incoming requests for all routes to heimdall. The code snippet below shows the corresponding AuthService resource which configures Emissary Ingress to let Envoy communicate over the GRPC protocol with heimdall.

apiVersion: getambassador.io/v3alpha1
kind: AuthService
metadata:
  name: heimdall
  namespace: heimdall
spec:
  auth_service: "https://<heimdall service name>.<namespace>.svc.cluster.local:<port>" (1)
  proto: grpc
  protocol_version: v3 (2)

1	Configures the controller to use heimdall’s main service endpoint with `<heimdall service name>`, `<namespace>` and `<port>` depending on your configuration. If heimdall is not operated in the same namespace as the ingress controller, it is important to configure the full DNS, otherwise Envoy will not be able to resolve the IP of heimdall.
2	Sets the used Envoy’s ExtAuth GRPC protocol version to v3, as this is the only version supported by heimdall. If not set, Emissary will default to v2.

The integration option shown above requires usage of the --envoy-grpc flag when starting heimdall. Unlike e.g. Contour, Emissary-Ingress allows however the usage of both, the Envoy’s external authorization GRPC protocol (used here), and the plain HTTP protocol.

Route-Level configuration

The single available configuration option on route level only supports disabling of request forwarding. That can be achieved by configuring a Mapping resource and setting bypass_auth to true (see also Bypass authentication).

Additional Resources

Checkout the examples on GitHub for a working demo.

Last updated on Feb 17, 2025

Contour Integration Envoy Integration