github.com/projectcontour/contour@v1.28.2/site/content/docs/v1.8.1/annotations.md (about)

     1  # Annotations Reference
     2  
     3  <div id="toc" class="navigation"></div>
     4  
     5  Annotations are used in Ingress Controllers to configure features that are not covered by the Kubernetes Ingress API.
     6  
     7  Some of the features that have been historically configured via annotations are supported as first-class features in Contour's [HTTPProxy API][15], which provides a more robust configuration interface over
     8  annotations.
     9  
    10  However, Contour still supports a number of annotations on the Ingress resources.
    11  
    12  ## Standard Kubernetes Ingress annotations
    13  
    14  The following Kubernetes annotations are supported on `Ingress` objects:
    15  
    16  ### Ingress Class
    17  
    18  The Ingress class annotation can be used to specify which Ingress controller should serve a particular Ingress object.
    19  This annotation may be specified as the standard `kubernetes.io/ingress.class` or a Contour-specific `projectcontour.io/ingress.class`.
    20  In both cases, they will behave as follows, by default:
    21  
    22  * If not set, then all Ingress controllers serve the Ingress.
    23  * If specified as `kubernetes.io/ingress.class: contour`, then Contour serves the Ingress.
    24  * If any other value, Contour ignores the Ingress definition.
    25  
    26  You can override the default class `contour` by providing the `--ingress-class-name` flag to Contour. 
    27  This can be useful while you are migrating from another controller, or if you need multiple instances of Contour.
    28  If you do this, the behavior is as follows:
    29  * If the annotation is not set, Contour will ignore the Ingress.
    30  * If the annotation is set to any value other than the one passed to the `--ingress-class-name` flag, Contour will ignore the Ingress.
    31  * If the annotation matches the value that you passed to `--ingress-class-name` flag, Contour will serve the Ingress.
    32  
    33  This same logic applies for these annotations on HTTPProxy objects.
    34  
    35  ### Other annotations 
    36  
    37   - `ingress.kubernetes.io/force-ssl-redirect`: Requires TLS/SSL for the Ingress to Envoy by setting the [Envoy virtual host option require_tls][16].
    38   - `kubernetes.io/ingress.allow-http`: Instructs Contour to not create an Envoy HTTP route for the virtual host. The Ingress exists only for HTTPS requests. Specify `"false"` for Envoy to mark the endpoint as HTTPS only. All other values are ignored.
    39  
    40  The `ingress.kubernetes.io/force-ssl-redirect` annotation takes precedence over `kubernetes.io/ingress.allow-http`. If they are set to `"true"` and `"false"` respectively, Contour *will* create an Envoy HTTP route for the Virtual host, and set the `require_tls` virtual host option.
    41  
    42  ## Contour specific Ingress annotations
    43  
    44   - `projectcontour.io/ingress.class`: The Ingress class that should interpret and serve the Ingress. See the [main Ingress class annotation section](#ingress-class) for more details.
    45   - `projectcontour.io/num-retries`: [The maximum number of retries][1] Envoy should make before abandoning and returning an error to the client. Applies only if `projectcontour.io/retry-on` is specified.
    46   - `projectcontour.io/per-try-timeout`: [The timeout per retry attempt][2], if there should be one. Applies only if `projectcontour.io/retry-on` is specified.
    47   - `projectcontour.io/response-timeout`: [The Envoy HTTP route timeout][3], specified as a [golang duration][4]. By default, Envoy has a 15 second timeout for a backend service to respond. Set this to `infinity` to specify that Envoy should never timeout the connection to the backend. Note that the value `0s` / zero has special semantics for Envoy.
    48   - `projectcontour.io/retry-on`: [The conditions for Envoy to retry a request][5]. See also [possible values and their meanings for `retry-on`][6].
    49   - `projectcontour.io/tls-minimum-protocol-version`: [The minimum TLS protocol version][7] the TLS listener should support.
    50   - `projectcontour.io/websocket-routes`: [The routes supporting websocket protocol][8], the annotation value contains a list of route paths separated by a comma that must match with the ones defined in the `Ingress` definition. Defaults to Envoy's default behavior which is `use_websocket` to `false`.
    51  
    52  ## Contour specific Service annotations
    53  
    54  A [Kubernetes Service][9] maps to an [Envoy Cluster][10]. Envoy clusters have many settings to control specific behaviors. These annotations allow access to some of those settings.
    55  
    56  - `projectcontour.io/max-connections`: [The maximum number of connections][11] that a single Envoy instance allows to the Kubernetes Service; defaults to 1024.
    57  - `projectcontour.io/max-pending-requests`: [The maximum number of pending requests][13] that a single Envoy instance allows to the Kubernetes Service; defaults to 1024.
    58  - `projectcontour.io/max-requests`: [The maximum parallel requests][13] a single Envoy instance allows to the Kubernetes Service; defaults to 1024
    59  - `projectcontour.io/max-retries`: [The maximum number of parallel retries][14] a single Envoy instance allows to the Kubernetes Service; defaults to 1024. This is independent of the per-Kubernetes Ingress number of retries (`projectcontour.io/num-retries`) and retry-on (`projectcontour.io/retry-on`), which control whether retries are attempted and how many times a single request can retry.
    60  - `projectcontour.io/upstream-protocol.{protocol}` : The protocol used to proxy requests to the upstream service.
    61    The annotation value contains a comma-separated list of port names and/or numbers that must match with the ones defined in the `Service` definition.
    62    This value can also be specified in the `spec.routes.services[].protocol` field on the HTTPProxy object, where it takes precedence over the Service annotation.
    63    Supported protocol names are: `h2`, `h2c`, and `tls`:
    64    - The `tls` protocol allows for requests which terminate at Envoy to proxy via TLS to the upstream.
    65      This protocol should be used for HTTP/1.1 services over TLS.
    66      _Note that validating the upstream TLS certificate requires additionally setting the [validation][17] field._
    67    - The `h2` protocol proxies requests to the upstream using HTTP/2 over TLS.
    68    - The `h2c` protocol proxies requests to the upstream using cleartext HTTP/2.
    69  
    70  ## Contour specific HTTPProxy annotations
    71  - `projectcontour.io/ingress.class`: The Ingress class that should interpret and serve the HTTPProxy. See the [main Ingress class annotation section](#ingress-class) for more details.
    72  
    73  [1]: https://www.envoyproxy.io/docs/envoy/v1.11.2/configuration/http_filters/router_filter.html#config-http-filters-router-x-envoy-max-retries
    74  [2]: https://www.envoyproxy.io/docs/envoy/v1.11.2/api-v2/api/v2/route/route.proto#envoy-api-field-route-routeaction-retrypolicy-retry-on
    75  [3]: https://www.envoyproxy.io/docs/envoy/v1.11.2/api-v2/api/v2/route/route.proto.html#envoy-api-field-route-routeaction-timeout
    76  [4]: https://golang.org/pkg/time/#ParseDuration
    77  [5]: https://www.envoyproxy.io/docs/envoy/v1.11.2/api-v2/api/v2/route/route.proto#envoy-api-field-route-routeaction-retrypolicy-retry-on
    78  [6]: https://www.envoyproxy.io/docs/envoy/v1.11.2/configuration/http_filters/router_filter.html#config-http-filters-router-x-envoy-retry-on
    79  [7]: https://www.envoyproxy.io/docs/envoy/v1.11.2/api-v2/api/v2/auth/cert.proto#envoy-api-msg-auth-tlsparameters
    80  [8]: https://www.envoyproxy.io/docs/envoy/v1.11.2/api-v2/api/v2/route/route.proto#envoy-api-field-route-routeaction-use-websocket
    81  [9]: https://kubernetes.io/docs/concepts/services-networking/service/
    82  [10]: https://www.envoyproxy.io/docs/envoy/v1.11.2/intro/arch_overview/intro/terminology.html
    83  [11]: https://www.envoyproxy.io/docs/envoy/v1.11.2/api-v2/api/v2/cluster/circuit_breaker.proto#envoy-api-field-cluster-circuitbreakers-thresholds-max-connections
    84  [12]: https://www.envoyproxy.io/docs/envoy/v1.11.2/api-v2/api/v2/cluster/circuit_breaker.proto#envoy-api-field-cluster-circuitbreakers-thresholds-max-pending-requests
    85  [13]: https://www.envoyproxy.io/docs/envoy/v1.11.2/api-v2/api/v2/cluster/circuit_breaker.proto#envoy-api-field-cluster-circuitbreakers-thresholds-max-requests
    86  [14]: https://www.envoyproxy.io/docs/envoy/v1.11.2/api-v2/api/v2/cluster/circuit_breaker.proto#envoy-api-field-cluster-circuitbreakers-thresholds-max-retries
    87  [15]: httpproxy.md
    88  [16]: https://www.envoyproxy.io/docs/envoy/v1.11.2/api-v2/api/v2/route/route.proto.html#envoy-api-field-route-virtualhost-require-tls
    89  [17]: /docs/{{page.version}}/api/#projectcontour.io/v1.UpstreamValidation