github.com/projectcontour/contour@v1.28.2/site/content/docs/main/config/health-checks.md (about)

     1  # Upstream Health Checks
     2  
     3  ## HTTP Proxy Health Checking
     4  
     5  Active health checking can be configured on a per route basis.
     6  Contour supports HTTP health checking and can be configured with various settings to tune the behavior.
     7  
     8  During HTTP health checking Envoy will send an HTTP request to the upstream Endpoints.
     9  It expects a 200 response by default if the host is healthy (see `expectedStatuses` below for configuring the "healthy" status codes).
    10  The upstream host can return 503 if it wants to immediately notify Envoy to no longer forward traffic to it.
    11  It is important to note that these are health checks which Envoy implements and are separate from any other system such as those that exist in Kubernetes.
    12  
    13  ```yaml
    14  # httpproxy-health-checks.yaml
    15  apiVersion: projectcontour.io/v1
    16  kind: HTTPProxy
    17  metadata:
    18    name: health-check
    19    namespace: default
    20  spec:
    21    virtualhost:
    22      fqdn: health.bar.com
    23    routes:
    24    - conditions:
    25      - prefix: /
    26      healthCheckPolicy:
    27        path: /healthy
    28        intervalSeconds: 5
    29        timeoutSeconds: 2
    30        unhealthyThresholdCount: 3
    31        healthyThresholdCount: 5
    32      services:
    33        - name: s1-health
    34          port: 80
    35        - name: s2-health
    36          port: 80
    37  ```
    38  
    39  Health check configuration parameters:
    40  
    41  - `path`: HTTP endpoint used to perform health checks on upstream service (e.g. `/healthz`). It expects a 200 response if the host is healthy. The upstream host can return 503 if it wants to immediately notify downstream hosts to no longer forward traffic to it.
    42  - `host`: The value of the host header in the HTTP health check request. If left empty (default value), the name "contour-envoy-healthcheck" will be used.
    43  - `intervalSeconds`: The interval (seconds) between health checks. Defaults to 5 seconds if not set.
    44  - `timeoutSeconds`: The time to wait (seconds) for a health check response. If the timeout is reached the health check attempt will be considered a failure. Defaults to 2 seconds if not set.
    45  - `unhealthyThresholdCount`: The number of unhealthy health checks required before a host is marked unhealthy. Note that for http health checking if a host responds with 503 this threshold is ignored and the host is considered unhealthy immediately. Defaults to 3 if not defined.
    46  - `healthyThresholdCount`: The number of healthy health checks required before a host is marked healthy. Note that during startup, only a single successful health check is required to mark a host healthy.
    47  - `expectedStatuses`: An optional list of HTTP status ranges that are considered healthy. Ranges follow half-open semantics, meaning the start is inclusive and the end is exclusive. Statuses must be between 100 (inclusive) and 600 (exclusive).
    48  
    49  ### Non-default expected statuses
    50  
    51  By default, only responses with a 200 status code will be considered healthy.
    52  The set of response codes considered healthy can be customized by specifying ranges in `expectedStatuses`.
    53  Ranges follow half-open semantics, meaning the start is inclusive and the end is exclusive. 
    54  Statuses must be between 100 (inclusive) and 600 (exclusive).
    55  For example:
    56  
    57  ```yaml
    58  apiVersion: projectcontour.io/v1
    59  kind: HTTPProxy
    60  metadata:
    61    name: health-check
    62    namespace: default
    63  spec:
    64    virtualhost:
    65      fqdn: health.bar.com
    66    routes:
    67    - conditions:
    68      - prefix: /
    69      healthCheckPolicy:
    70        path: /healthy
    71        intervalSeconds: 5
    72        timeoutSeconds: 2
    73        unhealthyThresholdCount: 3
    74        healthyThresholdCount: 5
    75        # Status codes 200 and 250-299 will be considered healthy.
    76        expectedStatuses:
    77        - start: 200
    78          end: 201
    79        - start: 250
    80          end: 300
    81      services:
    82        - name: s1-health
    83          port: 80
    84        - name: s2-health
    85          port: 80
    86  ```
    87  
    88  Note that if `expectedStatuses` is specified, `200` must be explicitly included in one of the specified ranges if it is desired as a healthy status code.
    89  
    90  ## TCP Proxy Health Checking
    91  
    92  Contour also supports TCP health checking and can be configured with various settings to tune the behavior.
    93  
    94  During TCP health checking Envoy will send a connect-only health check to the upstream Endpoints.
    95  It is important to note that these are health checks which Envoy implements and are separate from any
    96  other system such as those that exist in Kubernetes.
    97  
    98  ```yaml
    99  apiVersion: projectcontour.io/v1
   100  kind: HTTPProxy
   101  metadata:
   102    name: tcp-health-check
   103    namespace: default
   104  spec:
   105    virtualhost:
   106      fqdn: health.bar.com
   107    tcpproxy:
   108      healthCheckPolicy:
   109        intervalSeconds: 5
   110        timeoutSeconds: 2
   111        unhealthyThresholdCount: 3
   112        healthyThresholdCount: 5
   113      services:
   114        - name: s1-health
   115          port: 80
   116        - name: s2-health
   117          port: 80
   118  ```
   119  
   120  TCP Health check policy configuration parameters:
   121  
   122  - `intervalSeconds`: The interval (seconds) between health checks. Defaults to 5 seconds if not set.
   123  - `timeoutSeconds`: The time to wait (seconds) for a health check response. If the timeout is reached the health check attempt will be considered a failure. Defaults to 2 seconds if not set.
   124  - `unhealthyThresholdCount`: The number of unhealthy health checks required before a host is marked unhealthy. Note that for http health checking if a host responds with 503 this threshold is ignored and the host is considered unhealthy immediately. Defaults to 3 if not defined.
   125  - `healthyThresholdCount`: The number of healthy health checks required before a host is marked healthy. Note that during startup, only a single successful health check is required to mark a host healthy.
   126  
   127  ## Specify the service health check port
   128  
   129  contour supports configuring an optional health check port for services.
   130  
   131  By default, the service's health check port is the same as the service's routing port.
   132  If the service's health check port and routing port are different, you can configure the health check port separately.
   133  
   134  ```yaml
   135  apiVersion: projectcontour.io/v1
   136  kind: HTTPProxy
   137  metadata:
   138    name: health-check
   139    namespace: default
   140  spec:
   141    virtualhost:
   142      fqdn: health.bar.com
   143    routes:
   144    - conditions:
   145      - prefix: /
   146      healthCheckPolicy:
   147        path: /healthy
   148        intervalSeconds: 5
   149        timeoutSeconds: 2
   150        unhealthyThresholdCount: 3
   151        healthyThresholdCount: 5
   152      services:
   153        - name: s1-health
   154          port: 80
   155          healthPort: 8998
   156        - name: s2-health
   157          port: 80
   158  ```
   159  
   160  In this example, envoy will send a health check request to port `8998` of the `s1-health` service and port `80` of the `s2-health` service respectively . If the host is healthy, envoy will forward traffic to the `s1-health` service on port `80` and to the `s2-health` service on port `80`.