Project: Contour (Orchestration & Management / Service Proxy)
File: CHANGELOG-v1.24.0.md

We are delighted to present version v1.24.0 of Contour, our layer 7 HTTP reverse proxy for Kubernetes clusters. A big thank you to everyone who contributed to the release. Duplicate include conditions are now correctly identified and HTTPProxies are marked with the condition `IncludeError` and reason `DuplicateMatchConditions`. Previously the HTTPProxy processor was only comparing adjacent includes and comparing conditions element by element rather than as a whole, ANDed together. In addition, the previous behavior when duplicate Include Conditions were identified was to throw out all routes, including valid ones, on the offending HTTPProxy. Any referenced child HTTPProxies were marked as `Orphaned` as a result, even if they were included correctly. With this change, all valid Includes and Route rules are processed and programmed in the data plane, which is a difference in behavior from previous releases. An Include is deemed to be a duplicate if it has the exact same match Conditions as an Include that precedes it in the list. Only child HTTPProxies that are referenced by a duplicate Include and not in any other valid Include are marked as `Orphaned` A caveat to the above, is that an empty list of include conditions or a set of conditions that only consist of the prefix match on `/` are not treated as duplicates. This special case has been added because many users rely on the behavior this enables and many Contour examples demonstrating inclusion actually use it. For example: ``` apiVersion: projectcontour.io/v1 kind: HTTPProxy metadata: name: example spec: virtualhost: fqdn: foo-example.bar.com includes: name: example-child1 name: example-child2 apiVersion: projectcontour.io/v1 kind: HTTPProxy metadata: name: example-child1 spec: routes: conditions: prefix: / services: name: s1 port: 80 apiVersion: projectcontour.io/v1 kind: HTTPProxy metadata: name: example-child2 spec: routes: conditions: prefix: /foo services: name: s2 port: 80 ``` While the include conditions are equivalent, the resulting routing rules when the child routes are taken into account are distinct. This special casing is a stop-gap for this release, to ensure we do not break user's configuration that is currently valid and working. Currently duplicate route conditions are not checked in an HTTPProxy include tree or within an individual HTTPProxy. This means that you can have routes listed later in the list of routes on an HTTPProxy silently override others. The same can happen if you have an include tree that generates duplicate routes based on the include conditions and route conditions. If you are relying on this behavior, changes will be coming in the next Contour release. We will be submitting a design document to address this as it will be a significant behavior change and encourage the community to weigh in. The current plan is to fully validate duplicate route match conditions as they are generated from the tree of includes and routes. There will likely be changes to status conditions set on HTTPRoutes to improve reporting such invalid configuration. (#4931, #5017, @sunjayBhatia) See for more detail on the API

This version of the API includes a few changes relevant to Contour users: The ReferenceGrant resource has been graduated to the v1beta1 API and ReferencePolicy removed from the API v1alpha2 versions of GatewayClass, Gateway, and HTTPRoute are deprecated There have been significant changes to status conditions on various resources for consistency: Accepted and Programmed conditions have been added to Gateway and Gateway Listener The Ready condition has been moved to "extended" conformance, at this moment Contour does not program this condition The Scheduled condition has been deprecated on Gateway (#4944, @sunjayBhatia) The liveness probe has been removed from the Envoy pods' shutdown-manager sidecar container. This change is to mitigate a problem where when the liveness probe fails, the shutdown-manager container is restarted by itself. This ultimately has the unintended effect of causing the envoy container to be stuck indefinitely in a "DRAINING" state and not serving traffic. Overall, not having the liveness probe on the shutdown-manager container is less bad because envoy pods are less likely to get stuck in "DRAINING" indefinitely. In the worst case, during termination of an Envoy pod (due to upgrade, scaling, etc.), shutdown-manager is truly unresponsive, in which case the envoy container will simply terminate without first draining active connections. If appropriate (i.e. during an upgrade), a new Envoy pod will then be created and re-added to the set of ready Envoys to load balance traffic to. (#4967, @skriss) HTTPProxy.Route.Service and HTTPProxy.TCPProxy.Service now has an optional `HealthPort` field which specifies a health check port that is different from the routing port. If not specified, the service `Port` field is used for healthchecking. (#4761, @yangyy93) Contour no longer validates Secrets that are not used by an Ingress, HTTPProxy, Gateway, or Contour global config. Validation is now performed as needed when a Secret is referenced. This change also replaces misleading "Secret not found" error conditions with more specific errors when a Secret referenced by one of the above objects does exist, but is not valid. (#4788, @skriss) By default, when client certificate validation is configured, client certificates are required. However, some applications might support different authentication schemes. You can now set the `httpproxy.spec.virtualhost.tls.clientValidation.optionalClientCertificate` field to `true`. A client certificate will be requested, but the connection is allowed to continue if the client does not provide one. If a client certificate is sent, it will be verified according to the other properties, which includes disabling validations if `httpproxy.spec.virtualhost.tls.clientValidation.skipClientCertValidation` is set. (#4796, @gautierdelorme) HTTPProxy now supports passing certificate data through the `x-forwarded-client-cert` header to let applications use details from client certificates (e.g. Subject, SAN...). Since the certificate (or the certificate chain) could exceed the web server header size limit, you have the ability to select what specific part of the certificate to expose in the header through the `httpproxy.spec.virtualhost.tls.clientValidation.forwardClientCertificate` field. Read more about the supported values in the . (#4797, @gautierdelorme) Envoy's treatment of the Server header on responses can now be configured in the Contour config file or ContourConfiguration CRD. When configured as `overwrite`, Envoy overwrites any Server header with "envoy". When configured as `appendifabsent`, if a Server header is present, Envoy will pass it through, otherwise, it will set it to "envoy". When configured as `pass_through`, Envoy passes through the value of the Server header and does not append a header if none is present. (#4906, @Vishal-Chdhry) If `ALL` is specified, the DNS resolver will perform a lookup for both IPv4 and IPv6 families, and return all resolved addresses. When this is used, Happy Eyeballs will be enabled for upstream connections. (#4909, @Vishal-Chdhry) Bumps Envoy to version 1.25.0. See Envoy release notes . (#4988, @skriss) Contour's Kubernetes API client defaults to allowing 5 requests per second, with a maximum of 10 over a short period. These settings can now be configured, either by flag or by config file. The `contour serve` flags are `--kubernetes-client-qps` and `--kubernetes-client-burst`. The config file fields are `kubernetesClientQPS` and `kubernetesClientBurst`. (#5003, @skriss) Add (update)Strategy configurability to ContourDeployment resource for

(#4713, @izturn) Don't trigger DAG rebuilds for updates/deletes of unrelated Secrets. (#4792, @skriss) Allow TLS certificate secrets to be of type `Opaque` as long as they have valid `tls.crt` and `tls.key` entries. (#4799, @skriss) Add Envoy log level configurability to ContourDeployment resource. (#4801, @izturn) Add Service/Envoy's ExternalTrafficPolicy configurability to ContourDeployment resource. (#4803, @izturn) Deprecated Envoy xDS APIs from Envoy 1.24.0 are no longer in use, see for details on their replacements. (#4822, @sunjayBhatia) Don't trigger DAG rebuilds for updates/deletes of unrelated Services. (#4827, @Vishal-Chdhry) Fixed bug where ExtensionServices were being updated continuously by Contour (#4846, @Vishal-Chdhry) Add `grpcstatusnumber` to the default JSON access log fields (#4880, @rajatvig) Implement support for Gateway API HTTPRoute ResponseHeaderModifier filter. (#4908, @sunjayBhatia) Don't trigger DAG rebuilds/xDS configuration updates for irrelevant HTTPRoutes and TLSRoutes. (#4912, @fangfpeng) Ensure changes to Services referenced by TLSRoute trigger xDS configuration updates. (#4915, @vmw-yingy) Supported/tested Kubernetes versions are now 1.24, 1.25, 1.26. (#4937, @skriss) Sort and ensure the option flags in lexicographic order, fix (#4958, @izturn) Gateway API: adds support for the , which allows for rewriting the path or Host header as requests are being forwarded to the backend. (#4962, @skriss) expose configuration for envoy's RateLimitedAsResourceExhausted (#4971, @vroldanbet) Gateway API: when provisioning an Envoy `NodePortService`, use the Listeners' port numbers to populate the Service's node port values. (#4973, @izturn) Updates to Go 1.19.5. See the for more information. (#4980, @skriss) Improve xDS server logging on connection close to be less verbose by default. Previously all closed connections from Envoy xDS resource subscriptions were logged as errors. (#4993, @sunjayBhatia) Adds a new summary metric, `contourdagrebuildseconds`, to measure the duration of DAG rebuilds by quantile. (#5009, @skriss) Fixes a bug where the CLI did not have its Logger initialized which was resulting in a panic. (#5015, @skriss) Update for Go 1.19+. (#4813, @moeyui1) Added a section to the document describing how to deploy more than one Contour instance in a single cluster. (#4832, @skriss) Add get involved section in front page of the project contour. (#4847, @theVJagrawal) Gateway API: change the default controller name from `projectcontour.io/projectcontour/contour` to `projectcontour.io/gateway-controller` for static provisioning. (#4966, @izturn) Guides are now versioned along with the rest of Contour's documentation. You can find them listed in the menu on the left-hand side of https://projectcontour.io/docs. (#4977, @skriss) `ContourDeployment.Spec.Contour.Replicas` is deprecated and has been replaced by `ContourDeployment.Spec.Contour.Deployment.Replicas`. Users should switch to using the new field. The deprecated field will be removed in a future release. See #4713 for additional details. `ContourDeployment.Spec.Envoy.Replicas` is deprecated and has been replaced by `ContourDeployment.Spec.Envoy.Deployment.Replicas`. Users should switch to using the new field. The deprecated field will be removed in a future release. See #4713 for additional details. (#4713, @izturn) In Gateway API, ReferencePolicy's rename to ReferenceGrant has been fully completed. Contour now only supports ReferenceGrant, and does not support ReferencePolicy resources in any way. (#4830, @skriss) For a fresh install of Contour, consult the . To upgrade an existing Contour installation, please consult the . Contour v1.24.0 is tested against Kubernetes 1.24 through 1.26. Were immensely grateful for all the community contributions that help make Contour even better! For this release, special thanks go out to the following contributors: @Vishal-Chdhry @fangfpeng @gautierdelorme @izturn @moeyui1 @rajatvig @theVJagrawal @vmw-yingy @vroldanbet @yangyy93 If you're using Contour and want to add your organization to our adopters list, please visit this . If you prefer to keep your organization name anonymous but still give us feedback into your usage and scenarios for Contour, please post on this .