Contour Integration

Contour is an open source, high performance ingress controller for Kubernetes, implementing a control plane for Envoy edge and a service proxy.

When operating heimdall in Decision Operation Mode exposing Envoy’s external authorization GRPC protocol, integration with Contour can be achieved by creating an ExtensionService resource for heimdall and either an HTTPProxy resource for the upstream service, referencing the aforesaid ExtensionService, or configure Contour to use it globally (for all routes).

The ExtensionService resource definition tells Contour to program Envoy with an upstream cluster directing traffic to heimdall. That way, as also described in the Envoy Integration Guide, Envoy will delegate authentication and authorization to heimdall. If heimdall answers with a 200 OK HTTP code, Envoy grants access and forwards the original request to the upstream service. Otherwise, the response from heimdall is treated as an error and is returned to the client.

Being security first ingress controller, Contour enforces TLS for communication between Envoy and any external authorization service. For that reason, heimdall must be configured with an appropriate key material and certificate. Same is actually also true for the http route definition of the actual upstream service.

The official External Authorization Guide from Contour describes the required steps in great detail. While following it, please make attention to the following details specific to heimdall:

If you use cert-manager, ensure the feature gate AdditionalCertificateOutputFormats is set to true. This let cert-manager creating secrets with a property named tls-combined.pem, combining both the key and the certificate in one object, as also typically provided by any other CA and expected by heimdall.
When you configure the Certificte resource to let cert-manager issue a TLS certificate for heimdall, configure the additionalOutputFormats property with the type CombinedPEM to make use of the aforesaid feature gate and have the tls-combined.pem property set in the resulting secret. Here a small snippet showing the relevant parts:
```
apiVersion: cert-manager.io/v1
kind: Certificate
spec:
  # ...
  additionalOutputFormats:
    - type: CombinedPEM
  # ...
```
If TLS is enabled, which, as said above, is required for integration with Contour, by default heimdall is configured to support TLS v1.3 only. However, it looks like Contour does not configure Envoy to support TLS v1.3 so that the communication with heimdall happens via TLS v1.2 and below. For that reason you have to configure the decision service of heimdall to TLS v1.2 being the minimum supported version. Otherwise, Envoy will not be able communicating with heimdall, resulting in 403 responses for any request. The following snippet shows the relevant parts in the heimdall configuration file:
```
# ...
serve:
  decision:
    tls:
      # important! see explanations above
      min_version: TLS1.2
      key_store:
        # path to the pem file with key and certificates
        path: /certs/tls-combined.pem
# ...
```
Ensure heimdall is started in Decision Operation Mode exposing Envoy’s external authorization GRPC protocol (achieved by passing the --envoy-grpc flag while starting heimdall) and the required secret with the TLS key material is available to the heimdall container. The following snippet shows the relevant values configuration if you use helm for installing/updating heimdall:
```
extraArgs:
  - --envoy-grpc
deployment:
  volumes:
  - name: tls-cert-volume
    secret:
      secretName: <name of the corresponding secret>
  volumeMounts:
  - name: tls-cert-volume
    readOnly: true
    mountPath: /certs
```

Checkout the examples on GitHub for a working demo.

Last updated on Nov 14, 2023

Security

Emissary Ingress Integration