Emissary Ingress Integration

Emissary-Ingress is an Envoy-powered open source, high performance ingress controller and API Gateway for Kubernetes from Ambassador Labs.

When operating heimdall in Decision Operation Mode, integration with Emissary-Ingress can be achieved by creating an AuthService resource for heimdall. If you’re using the commercial Ambassador Edge Stack, you have to use the External Filter instead, which spec is more or less identical to the AuthService resource referenced above. In both cases the underlying Envoy proxy will be configured to delegate authentication and authorization of all incoming requests for all routes to heimdall. There is also an option to disable that forwarding on a route level if required by configuring a Mapping resource and setting bypass_auth to true. This will tell Emissary-ingress to allow all requests for that Mapping through without interacting with the external auth service.

Both, the AuthService, as well as the Filter resources allow configuring Envoy to make use of either the HTTP, or the Envoy’s external authorization GRPC protocols. Both is supported by heimdall, and it is just a matter of making use of the --envoy-grpc flag when starting heimdall, to have it either listen to HTTP or Envoy’s GRPC requests.

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.

Example 1. AuthService resource

In this example the AuthService resource 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:<decision port>" (1)
  proto: grpc
  protocol_version: v3 (2)

1	Configures the controller to use heimdall’s decision service endpoint with `<heimdall service name>`, `<namespace>` and `<decision 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.

Checkout the examples on GitHub for a working demo.

Last updated on Nov 14, 2023

Contour Integration

Envoy Integration