How to configure upstream healthchecks with the Ingress Controller

When using the Kubernetes Ingress Controller and defining the Kong Objects using the Kubernetes Ingress resource, how can I define circuit breakers and active healthchecks?

For KIC versions 2.5 LTS and 2.12 LTS

If you need to configure circuit breakers and active healthchecks in Kubernetes, you can do it using the KongIngress resource object and annotating the Kubernetes Service object so that it references the defined KongIngress. As this is changing the upstream parameters, the annotation needs to go on the Kubernetes Service and not on the Ingress.

Once the Service has been annotated to use the KongIngress object that has been set with the upstream healthcheck parameters, Kong will update the upstream objects accordingly and provide the passive healthchecks (circuit breakers) and active healthchecks should you require them.

For example, you can define the following KongIngress:

apiVersion: configuration.konghq.com/v1
kind: KongIngress
metadata:
  name: sample-kong-ingress
upstream:
  hash_on: header
  hash_on_header: x-lb
  hash_fallback: ip
  algorithm: consistent-hashing
  healthchecks:
    passive:
      healthy:
        successes: 1
      unhealthy:
        http_failures: 5
        tcp_failures: 5
        timeouts: 3
    active:
      healthy:
        interval: 10
        successes: 1
      unhealthy:
        interval: 10
        http_failures: 5
        tcp_failures: 5
        timeouts: 3

Then, you need to annotate the Kubernetes Service as konghq.com/override so that the upstream gets configured accordingly:

annotations:
  konghq.com/override: sample-kong-ingress

You can find the Gateway Upstream healthchecks documentation in the related resources below.

For KIC version 3.1 and onwards

For Kubernetes Ingress Controller 3.1 and onwards, KongIngress is going to be removed and it is replaced with annotations in most cases, including healthchecks. See the annotation and custom resource references below.