github.com/nginxinc/kubernetes-ingress@v1.12.5/examples/health-checks/README.md (about)

     1  # Support for Active Health Checks
     2  
     3  NGINX Plus supports [active health checks](https://docs.nginx.com/nginx/admin-guide/load-balancer/http-health-check/#active-health-checks). To use active health checks in the Ingress controller:
     4  
     5  1. Define health checks ([HTTP Readiness Probe](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-probes/#define-readiness-probes)) in the templates of your application pods.
     6  2. Enable heath checks in the Ingress controller using the annotations.
     7  
     8  The Ingress controller provides the following annotations for configuring active health checks:
     9  
    10  * Required: `nginx.com/health-checks: "true"` -- enables active health checks. The default is `false`.
    11  * Optional: `nginx.com/health-checks-mandatory: "true"` -- configures active health checks as mandatory. With the default active health checks, when an endpoint is added to NGINX Plus via the API or after a configuration reload, NGINX Plus considers the endpoint to be healthy. With mandatory health checks, when an endpoint is added to NGINX Plus or after a configuration reload, NGINX Plus considers the endpoint to be unhealthy until its health check passes. The default is `false`.
    12  * Optional: `nginx.com/health-checks-mandatory-queue: "500"` -- configures a [queue](https://nginx.org/en/docs/http/ngx_http_upstream_module.html#queue) for temporary storing incoming requests during the time when NGINX Plus is checking the health of the endpoints after a configuration reload. If the queue is not configured or the queue is full, NGINX Plus will drop an incoming request returning the `502` code to the client. The queue is configured only when health checks are mandatory. The timeout parameter of the queue is configured with the value of the timeoutSeconds field of the corresponding Readiness Probe. Choose the size of the queue according with your requirements such as the expected number of requests per second and the timeout. The default is `0`.
    13  
    14  # Example
    15  
    16  In the following example we enable active health checks in the cafe-ingress Ingress:
    17  ```yaml
    18  apiVersion: networking.k8s.io/v1beta1
    19  kind: Ingress
    20  metadata:
    21    name: cafe-ingress
    22    annotations:
    23       kubernetes.io/ingress.class: "nginx"
    24       nginx.com/health-checks: "true"
    25  spec:
    26    rules:
    27    - host: "cafe.example.com"
    28      http:
    29        paths:
    30        - path: /tea
    31          backend:
    32            serviceName: tea-svc
    33            servicePort: 80
    34        - path: /coffee
    35          backend:
    36            serviceName: coffee-svc
    37            servicePort: 80
    38        - path: /beer
    39          backend:
    40            serviceName: beer-svc
    41            servicePort: 80
    42  ```
    43  
    44  Note that a Readiness Probe must be configured in the pod template:
    45  ```yaml
    46  apiVersion: extensions/v1beta1
    47  kind: Deployment
    48  metadata:
    49    name: tea
    50  spec:
    51    replicas: 3
    52    selector:
    53      matchLabels:
    54        app: tea
    55    template: 
    56      metadata:
    57        labels:
    58          app: tea
    59      spec:
    60        containers:
    61        - name: tea
    62          image: nginxdemos/nginx-hello:plain-text
    63          ports:
    64          - containerPort: 8080
    65          readinessProbe:
    66            httpGet:
    67              port: 8080
    68              path: /healthz/tea
    69              httpHeaders:
    70              - name: header1
    71                value: "some value"
    72              - name: header2
    73                value: "123"
    74            initialDelaySeconds: 1
    75            periodSeconds: 5
    76            timeoutSeconds: 4
    77            successThreshold: 2
    78            failureThreshold: 3
    79  ```