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

We are delighted to present version v1.21.0 of Contour, our layer 7 HTTP reverse proxy for Kubernetes clusters. A big thank you to everyone who contributed to the release. Previously, in our example deployment YAML, RBAC for Contour access to resources used for leader election was contained in a ClusterRole, meaning that Contour required cluster-wide access to ConfigMap resources. This release also requires Contour access to Events and Leases which would require cluster-wide access (see ). In this release, we have moved the RBAC rules for leader election resources to a namespaced Role in the example Contour deployment. This change should limit Contour's default required access footprint. A corresponding namespaced RoleBinding has been added as well. If you are using the example deployment YAML to deploy Contour, be sure to examine and re-apply the resources in `examples/contour/02-rbac.yaml` and `examples/contour/02-role-contour.yaml`. If you have deployed Contour in a namespace other than the example `projectcontour`, be sure to modify the `contour` Role and `contour-rolebinding` RoleBinding resources accordingly. Similarly, if you are using the `--leader-election-resource-namespace` flag to customize where Contour's leader election resources reside, you must customize the new Role and RoleBinding accordingly. (#4204, @sunjayBhatia) Contour's container images are now exclusively published . They are no longer being pushed to Docker Hub (past images have been left on Docker Hub for posterity.) (#4314, @skriss) Contour now has an optional Gateway provisioner, that watches for `Gateway` custom resources and provisions Contour + Envoy instances for them. The provisioner is implemented as a new subcommand on the `contour` binary, `contour gateway-provisioner`. The `examples/gateway-provisioner` directory contains the YAML manifests needed to run the provisioner as a Deployment in-cluster. By default, the Gateway provisioner will process all `GatewayClasses` that have a controller string of `projectcontour.io/gateway-controller`, along with all Gateways for them. The Gateway provisioner is useful for users who want to dynamically provision Contour + Envoy instances based on the `Gateway` CRD. It is also necessary in order to have a fully conformant Gateway API implementation. (#4415, @skriss) The verbosity of HTTP and HTTPS access logs can now be configured to one of: `info` (default), `error`, `disabled`. The verbosity level is set with `accesslog-level` field in the or `spec.envoy.logging.accessLogLevel` field in . (#4331, @tsaarni) Contour now only uses the Lease object to coordinate leader election. RBAC in example manifests has been updated accordingly. Note: Upgrading to this version of Contour will explicitly require you to upgrade to Contour v1.20.0 first to ensure proper migration of leader election coordination resources. (#4332, @sunjayBhatia) Regex patterns Contour configures in Envoy (for path matching etc.) currently have a limited "program size" (approximate cost) of 100. This was inadvertently set back to the Envoy default, from the intended 1048576 (2^20) when moving away from using deprecated API fields. Note: regex program size is a feature of the regex library Envoy uses,

This limit has now been reset to the intended value and an additional program size warning threshold of 1000 has been configured. Operators concerned with performance implications of allowing large regex programs can monitor Envoy memory usage and regex statistics. Envoy offers two statistics for monitoring regex program size, `re2.programsize` and `re2.exceededwarn_level`. See for more detail. Future versions of Contour may allow configuration of regex program size thresholds via RTDS (Runtime Discovery Service). (#4379, @sunjayBhatia) Contour can now optionally process a specific named `Gateway` and associated routes. This is an alternate way to configure Contour, vs. the existing mode of specifying a `GatewayClass` controller string and having Contour process the first `GatewayClass` and associated `Gateway` for that controller string. This new configuration option can be specified via: ```yaml gateway: gatewayRef: namespace: gateway-namespace name: gateway-name ``` (#4410, @skriss) The Gateway provisioner now supports having more than one Gateway/Contour instance per namespace. All resource names now include a `-<gateway-name>` suffix to avoid conflicts (cluster-scoped resources also include the namespace as part of the resource name). Contour instances are always provisioned in the namespace of the Gateway custom resource itself. (#4426, @skriss) The Gateway provisioner now generates xDS TLS certificates directly, rather than using a "certgen" job to trigger certificate generation. This simplifies operations and reduces the RBAC permissions that the provisioner requires. Certificates will still be rotated each time the provisioner is upgraded to a new version. (#4432, @skriss) The Gateway provisioner now supports requesting a specific Gateway address, via the Gateway's `spec.addresses` field. Only one address is supported, and it must be either an `IPAddress` or `Hostname` type. The value of this address will be used to set the provisioned Envoy service's `spec.loadBalancerIP` field. If for any reason, the requested address is not assigned to the Gateway, the Gateway will have a condition of "Ready: false" with a reason of `AddressesNotAssigned`. If no address is requested, no value will be specified in the provisioned Envoy service's `spec.loadBalancerIP` field, and an address will be assigned by the load balancer provider. (#4443, @skriss) To better manage configuration defaults, all `ContourConfiguration` CRD fields are now optional without defaults. Instead, Contour itself will apply defaults to any relevant fields that have not been specified by the user when it starts up, similarly to how processing of the Contour `ConfigMap` works today. The default values that Contour uses are documented in the `ContourConfiguration` CRD's API documentation. (#4451, @skriss) The `ContourDeployment` CRD, which can be used as parameters for a Contour-controlled `GatewayClass`, now supports additional options for customizing your Contour/Envoy installations: Contour deployment replica count Contour deployment node placement settings (node selectors and/or tolerations) Envoy workload type (daemonset or deployment) Envoy replica count (if using a deployment) Envoy service type and annotations Envoy node placement settings (node selectors and/or tolerations) (#4472, @skriss) Contour users can now configure their load balancing policies on `HTTPProxy` resources to hash the query parameter on a request to ensure consistent routing to a backend service

See for more details on this feature. Credit to @pkit for implementing this feature! (#4508, @sunjayBhatia) Allow the contour --ingress-class-name value to be a comma-separated list of classes to match against. Contour will process Ingress and HTTPProxy objects with any of the specified ingress classes. (Note that the alpha ContourConfiguration CRD has also been changed to use a ClassNames array field instead of a scalar ClassName field.) (#4109, @erwbgy) Don't check for or log errors for unsupported annotations on objects that Contour doesn't care about (e.g. ingresses for a different class than Contour's). (#4304, @skriss) Explicitly disable controller-runtime manager metrics and health listeners. (#4312, @sunjayBhatia) Removed code duplication for the secret validation in the dag package. (#4316, @alessandroargentieri) Node labels in `localhost:6060/debug/dag` troubleshooting API are sanitized by html-escaping user fields. (#4323, @kb000) Upstream TCP connection timeout is now configurable in and in . (#4326, @tsaarni) Drops RBAC and caching for the `networking.k8s.io/IngressClass` resource as it's not used by Contour. (#4329, @skriss) Fixed a bug where upstream TLS SNI (`HTTProxy.spec.routes.requestHeadersPolicy` `Host` key) and protocol fields might not take effect when e.g. two `HTTPProxies` were otherwise equal but differed only on those fields. (#4350, @tsaarni) New field `HTTPProxy.spec.routes.timeoutPolicy.idleConnection` was added. The field sets timeout for how long the upstream connection will be kept idle between requests before disconnecting it. (#4356, @tsaarni) Update github.com/prometheus/client_golang to v1.11.1 to address CVE-2022-21698. (#4361, @tsaarni) Envoy's option that enables a non-standard path transformation option to replace multiple consecutive slashes in an URL path with a single slash can now be disabled by setting the `DisableMergeSlashes` option in the Contour config file or ContourConfiguration custom resource. (#4363, @mszabo-wikia) Updates Envoy to v1.21.1. See the for details. (#4365, @skriss) Add base implementation for RTDS (Runtime Discovery Service). This will be used to enable dynamic configuration of Envoy Runtime settings. (#4380, @sunjayBhatia) Ensure controller-runtime logging is properly configured to log to Contour's logrus Logger instance. (#4391, @sunjayBhatia) Adds an optional `--name-prefix` flag to the `contour certgen` command which, if specified, will be added as a prefix to the names of the generated Kubernetes secrets (e.g. `myprefix-contourcert` and `myprefix-envoycert`). (#4394, @skriss) Moved all usages of headermatch and exactmatch with string_match (#4397, @rajatvig) Use the protocol field from the Cluster when performing the health check (#4398, @rajatvig) Removed the hack for ImagePullPolicy for certgen (#4402, @rajatvig) internal/envoy: Enable gzip compression for grpc-web content types. (#4403, @bourquep) In the example manifests, leave `imagePullPolicy` as `Always` on main branch and only change to `IfNotPresent` on release branches/release-tagged manifests. (#4406, @rajatvig) Upgrade to Go 1.18.0. (#4412, @skriss) Add grpc_stats filter for Envoy Add the ability to log "grpc_status" to the Envoy access log (#4424, @rajatvig) Gateway provisioner: set the GatewayClass "Accepted" condition based on the validity of its parametersRef, if it has one. Also only reconciles Gateways for GatewayClasses with "Accepted:

(#4440, @skriss) The Gateway provisioner now provisions a `ContourConfiguration` resource instead of a `ConfigMap` for describing Contour's configuration. (#4454, @skriss) Uses the `ContourConfigurationSpec` defined as part of a `GatewayClass's` `ContourDeployment` parameters when provisioning a `ContourConfiguration` for a `Gateway`. (#4459, @skriss) Gateway API: set appropriate conditions on Listeners if they don't specify the same port as other Listeners for their protocol group (i.e. HTTP, or HTTPS/TLS) or don't have a unique hostname within their group. (#4462, @skriss) Add a example to show how to do blue-green deployment under Gateway-API mode (#4466, @izturn) Fix improper use of OriginalIPDetectionFilter in HTTPConnectionManager. Reverts back to XffNumTrustedHops setting which was un-deprecated in Envoy 1.20. (#4470, @sunjayBhatia) Gateway provisioner: change default controller name to `projectcontour.io/gateway-controller`. (#4474, @skriss) Gateway API: when an `HTTPRoute` or `TLSRoute` has a cross-namespace backend ref that's not permitted by a `ReferencePolicy`, set the reason for the `ResolvedRefs: false` condition to `RefNotPermitted` instead of `Degraded`. (#4482, @skriss) Add support for Contour to produce logs in JSON format by specifying `--log-format=json` command line switch. (#4486, @tsaarni) Use typed config for all Envoy extensions in place of well-known names or internal type URL constants, for consistency and forwards-compatibility. (#4487, @skriss) Updates to Envoy 1.22.0. See the for more information. (#4488, @skriss) Updates Gateway API to v0.4.3 and adds the Gateway API validating webhook to Contour's Gateway API example YAML. (#4489, @skriss) Gateway API: adjusts logic for finding intersecting hostnames between a Listener and a Route to ignore non-matching hosts rather than reporting an error for them. (#4505, @skriss) Upgrade to Go 1.18.1. (#4509, @sunjayBhatia) Remove `ContourConfiguration` kubebuilder enum validations, and add equivalent validations in Contour code. (#4511, @skriss) Gateway API: fixes a bug where a route would be marked "Accepted: false" with reason "NoIntersectingHostnames" if it did not have intersecting hostnames with every Listener. Now, as long as the route's hostnames intersect with at least one Listener, it's accepted. (#4512, @skriss) The AWS NLB deployment guide has been updated, and the annotations `service.beta.kubernetes.io/aws-load-balancer-type` has been change to `external`. It should now work correctly with the given YAMLs. (#4347, @yankay) Added documentation for HTTPProxy request redirection. (#4367, @sunjayBhatia) Add `pathType` field to Ingress resource. (#4446, @lou-lan) Leader election configuration via configuration file was deprecated in Contour v1.20.0. Configuration of leader election lease details and resource must now be done via command line flag. (#4340, @sunjayBhatia) For a fresh install of Contour, consult the . To upgrade an existing Contour installation, please consult the . Contour v1.21.0 is tested against Kubernetes 1.21 through 1.23. 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: @alessandroargentieri @bourquep @erwbgy @izturn @kb000 @lou-lan @mszabo-wikia @rajatvig @yankay 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 .