Contour v1.20.2

We are delighted to present version v1.20.2 of Contour, our layer 7 HTTP reverse proxy for Kubernetes clusters.

A big thank you to everyone who contributed to the release.

• Minor Changes
• Other Changes
• Installing/Upgrading
• Compatible Kubernetes Versions
• Community Thanks!

Minor Changes

Bump Envoy to v1.21.3

Bumps Envoy to security patch version 1.21.3.
Envoy announcement here.
See Envoy release notes here.

(#4569, @sunjayBhatia)

Other Changes

• When validating secrets, don't log an error for an Opaque secret that doesn't contain a ca.crt key. (#4528, @skriss)
• Fixes TLS private key validation logic which previously ignored errors for PKCS1 and PKCS8 private keys. (#4544, @sunjayBhatia)
• Update gopkg.in/yaml.v3 to v3.0.1 to address CVE-2022-28948. (#4551, @tsaarni)

Installing and Upgrading

For a fresh install of Contour, consult the getting started documentation.

To upgrade an existing Contour installation, please consult the upgrade documentation.

Compatible Kubernetes Versions

Contour v1.20.2 is tested against Kubernetes 1.21 through 1.23.

Community Thanks!

We’re immensely grateful for all the community contributions that help make Contour even better!

Are you a Contour user? We would love to know!

If you're using Contour and want to add your organization to our adopters list, please visit this page. 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 GitHub thread.

Contour v1.21.0

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.

• Major Changes
• Minor Changes
• Other Changes
• Docs Changes
• Deprecations/Removals
• Installing/Upgrading
• Compatible Kubernetes Versions
• Community Thanks!

Major Changes

Contour leader election resource RBAC moved to namespaced Role

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 this PR).

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.

Required actions

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)

Container Images Now Exclusively Published on GitHub Container Registry (GHCR)

Contour's container images are now exclusively published on GHCR. They are no longer being pushed to Docker Hub (past images have been left on Docker Hub for posterity.)

(#4314, @skriss)

Adds a contour gateway-provisioner command and deployment manifest for dynamically provisioning Gateways

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)

Minor Changes

Configurable access log level

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 configuration file or spec.envoy.logging.accessLogLevel field in ContourConfiguration.

(#4331, @tsaarni)

Leader election now only uses Lease object

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)

Re-increase maximum allowed regex program size

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, Google RE2.

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.program_size and re2.exceeded_warn_level. See this documentation for more detail. Future versions of Contour may allow configuration of regex program size thresholds via RTDS (Runtime Discovery Service).

(#4379, @sunjayBhatia)

Gateway API: support for processing a specific Gateway

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:

gateway:
  gatewayRef:
    namespace: gateway-namespace
    name: gateway-name

(#4410, @skriss)

Gateway provisioner: add support for more than one Gateway/Contour instance per namespace

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)

Gateway provisioner: generate xDS TLS certs directly

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)

Gateway provisioner: support requesting a specific address

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)

All ContourConfiguration CRD fields are now optional

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)

ContourDeployment CRD now supports additional options

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)

Query parameter hash based load balancing

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 instance.

See this page for more details on this feature.

Credit to @pkit for implementing this feature!

(#4508, @sunjayBhatia)

Other Changes

• 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 configuration file and in [ContourConfiguration](https...

Contour v1.21.0-rc.1

We are delighted to present version v1.21.0-rc.1 of Contour, our layer 7 HTTP reverse proxy for Kubernetes clusters.

A big thank you to everyone who contributed to the release.

Please note that this is pre-release software, and as such we do not recommend installing it in production environments.
Feedback and bug reports are welcome!

• Major Changes
• Minor Changes
• Other Changes
• Docs Changes
• Deprecations/Removals
• Installing
• Compatible Kubernetes Versions
• Community Thanks!

Major Changes

Contour leader election resource RBAC moved to namespaced Role

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 this PR).

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.

Required actions

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)

Container Images Now Exclusively Published on GitHub Container Registry (GHCR)

Contour's container images are now exclusively published on GHCR. They are no longer being pushed to Docker Hub (past images have been left on Docker Hub for posterity.)

(#4314, @skriss)

Adds a contour gateway-provisioner command and deployment manifest for dynamically provisioning Gateways

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-provisioner, 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)

Minor Changes

Configurable access log level

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 configuration file or spec.envoy.logging.accessLogLevel field in ContourConfiguration.

(#4331, @tsaarni)

Leader election now only uses Lease object

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)

Re-increase maximum allowed regex program size

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, Google RE2.

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.program_size and re2.exceeded_warn_level.
See this documentation for more detail.
Future versions of Contour may allow configuration of regex program size thresholds via RTDS (Runtime Discovery Service).

(#4379, @sunjayBhatia)

Gateway API: support for processing a specific Gateway

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:

gateway:
  gatewayRef:
    namespace: gateway-namespace
    name: gateway-name

(#4410, @skriss)

Gateway provisioner: add support for more than one Gateway/Contour instance per namespace

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)

Gateway provisioner: generate xDS TLS certs directly

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)

Gateway provisioner: support requesting a specific address

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)

All ContourConfiguration CRD fields are now optional

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)

ContourDeployment CRD now supports additional options

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)

Other Changes

• 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 configuration file and in ContourConfiguration. (#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.spe...

Contour v1.20.1

We are delighted to present version v1.20.1 of Contour, our layer 7 HTTP reverse proxy for Kubernetes clusters.

A big thank you to everyone who contributed to the release.

• Changes
• Docs Changes
• Deprecations/Removals
• Installing/Upgrading
• Compatible Kubernetes Versions

Changes

• 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)
• Update github.com/prometheus/client_golang to v1.11.1 to address CVE-2022-21698. (#4361, @tsaarni)
• Updates Envoy to v1.21.1. See the Envoy changelog for details. (#4365, @skriss)

Docs Changes

• Added documentation for HTTPProxy request redirection. (#4367, @sunjayBhatia)

Installing and Upgrading

For a fresh install of Contour, consult the getting started documentation.

To upgrade an existing Contour installation, please consult the upgrade documentation.

Compatible Kubernetes Versions

Contour v1.20.1 is tested against Kubernetes 1.21 through 1.23.

Are you a Contour user? We would love to know!

If you're using Contour and want to add your organization to our adopters list, please visit this page. 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 GitHub thread.

Contour v1.20.0

We are delighted to present version v1.20.0 of Contour, our layer 7 HTTP reverse proxy for Kubernetes clusters.

A big thank you to everyone who contributed to the release.

Major Changes

Gateway API v1alpha2 support

Contour now exclusively supports Gateway API v1alpha2, the latest available version.
This version of Gateway API has a number of breaking changes, which are detailed in the Gateway API changelog.
Contour currently supports a single GatewayClass and associated Gateway, and HTTPRoutes and TLSRoutes that attach to the Gateway. TCPRoute and UDPRoute are not supported.
For a list of other functionality that remains to be implemented, see Contour's area/gateway-api label.

As part of this change, support for Gateway API v1alpha1 has been dropped, and any v1alpha1 resources will not be automatically converted to v1alpha2 resources because the API has moved to a different API group (from networking.x-k8s.io to gateway.networking.k8s.io).

(#4047, @skriss)

xDS management connection between Contour and Envoy set to TLSv1.3

The minimum accepted TLS version for Contour xDS server is changed from TLSv1.2 to TLSv1.3.
Previously in Contour 1.19, the maximum accepted TLS version for Envoy xDS client was increased to TLSv1.3 which allows it to connect to Contour xDS server using TLSv1.3.

If upgrading from a version prior to Contour 1.19, the old Envoys will be unable to connect to new Contour until also Envoys are upgraded.
Until that, old Envoys are unable to receive new configuration data.

For further information, see Contour architecture and xDS API in Envoy documentation.

(#4065, @tsaarni)

Minor Changes

Metrics over HTTPS

Both Envoy and Contour metrics can now be served over HTTPS.
Server can alternatively also require client to present certificate which is validated against configured CA certificate.
This feature makes it possible to limit the visibility of metrics to authorized clients.

(#3707, @tsaarni)

Performance improvement for processing configuration

The performance of Contour's configuration processing has been made more efficient, particularly for clusters with large numbers (i.e. >1k) of HTTPProxies and/or Ingresses.
This means that there should be less of a delay between creating/updating an HTTPProxy/Ingress in Kubernetes, and having it reflected in Envoy's configuration.

(#4099, @skriss)

Allow retry policy, num retries to be zero

The field, NumRetries (e.g. count), in the RetryPolicy allows for a zero to be
specified, however Contour's internal logic would see that as "undefined"
and set it back to the Envoy default of 1. This would never allow the value of
zero to be set. Users can set the value to be -1 which will represent disabling
the retry count. If not specified or set to zero, then the Envoy default value
of 1 is used.

(#4117, @stevesloka)

Gateway API: implement PathPrefix matching

Contour now implements Gateway API v1alpha2's "path prefix" matching for HTTPRoutes.
This is now the only native form of prefix matching supported by Gateway API, and is a change from v1alpha1.
Path prefix matching means that the prefix specified in an HTTPRoute rule must match entire segments of a request's path in order to match it, rather than just be a string prefix.
For example, the prefix /foo would match a request for the path /foo/bar but not /foobar.
For more information, see the Gateway API documentation.

(#4119, @skriss)

Add Envoy Deployment Example

The examples now include a way to deploy Envoy as a Deployment vs a Daemonset.
This can assist in allowing Envoy to drain connections cleanly when the Kubernetes cluster size is scaled down.

(#4126, @stevesloka)

Default status on HTTPProxy resources

When a new HTTPProxy is created, if Contour isn't yet running or
functioning properly, then no status is set on the resource.
Defaults of "NotReconciled/Waiting for controller" are now applied
to any new object until an instance of Contour accepts the
object and updates the status.

(#4133, @stevesloka)

Gateway API: support ReferencePolicy

Contour now supports the ReferencePolicy CRD in Gateway API v1alpha2.
ReferencePolicy enables certain cross-namespace references to be allowed in Gateway API.
The primary use case is to enable routes (e.g. HTTPRoutes, TLSRoutes) to reference backend Services in different namespaces.
When Contour processes a route that references a service in a different namespace, it will check for a ReferencePolicy that applies to the route and service, and if one exists, it will allow the reference.

(#4138, @skriss)

Source IP hash based load balancing

Contour users can now configure their load balancing policies on HTTPProxy resources to hash the source IP of a client to ensure consistent routing to a backend service instance. Using this feature combined with header value hashing can implement advanced request routing and session affinity. Note that if you are using a load balancer to front your Envoy deployment, you will need to ensure it preserves client source IP addresses to ensure this feature is effective.

See this page for more details on this feature.

(#4141, @sunjayBhatia)

Gateway API: set Gateway Listener status fields

Contour now sets the .status.listeners.supportedKinds and .status.listeners.attachedRoutes fields on Gateways for Gateway API.
The first describes the list of route groups/kinds that the listener supports, and the second captures the total number of routes that are successfully attached to the listener.

(#4160, @skriss)

TLS Certificate validation updates

Contour now allows non-server certificates that do not have a CN or SAN set, which mostly fixes
#2372 and #3889.

TLS documentation has been updated to make the rules for Secrets holding TLS information clearer.

Those rules are:

For certificates that identify a server, they must:

• be kubernetes.io/tls type
• contain tls.crt, and tls.key keys with the server certificate and key respectively.
• have the first certificate in the tls.crt bundle have a CN or SAN field set.

They may:

• have the tls.crt key contain a certificate chain, as long as the first certificate in the chain is the server certificate.
• add a ca.crt key that contains a Certificate Authority (CA) certificate or certificates.

Certificates in the certificate chain that are not server certificates do not need to have a CN or SAN.

For CA secrets, they must:

• be Opaque type
• contain only a ca.crt key, not tls.crt or tls.key

The ca.crt key may contain one or more CA certificates, that do not need to have a CN or SAN.

(#4165, @youngnick)

HTTPProxy TCPProxy service weights are now applied

Previously, Contour did not apply any service weights defined in an HTTPProxy's TCPProxy, and all services were equally weighted.
Now, if those weights are defined, they are applied so traffic is weighted appropriately across the services.
Note that if no TCPProxy service weights are defined, traffic continues to be equally spread across all services.

(#4169, @skriss)

Leader Election Configuration

contour serve leader election configuration via config file has been deprecated.
The preferred way to configure leader election parameters is now via command line flags.
See here for more detail on the new leader election flags.

Note: If you are using the v1alpha1 ContourConfiguration CRD, leader election configuration has been removed from that CRD as well.
Leader election configuration is not something that will be dynamically configurable once Contour implements configuration reloading via that CRD.

(#4171, @sunjayBhatia)

Set Gateway listener conditions

Contour now sets various Gateway listener conditions as it processes them, including the "Ready", "Detached", and "ResolvedRefs" condition types, to provide more visibility to the user as to whether their listeners are defined correctly or not.

(#4186, @skriss)

HTTP Request Redirect Policy

HTTPProxy.Route now has a HTTPRequestRedirectPolicy which allows for routes to specify a RequestRedirectPolicy.
This policy will allow a redirect to be configured for a specific set of Conditions within a single route.
The policy can be configured with a Hostname, StatusCode, Scheme, and Port.

Additionally, Services on a Route are now optional when a request redirect is defined.

(#4201, @stevesloka)

Transition to controller-runtime managed leader election

Contour now utilizes controller-runtime Manager based leader election and coordination of subroutines.
With this change, Contour is also transitioning away from using a ConfigMap for leader election.
In this release, Contour now uses a combination of ConfigMap and Lease object.
A future release will remove usage of the ConfigMap resource for leader election.

This change should be a no-op for most users, however be sure to re-apply the relevant parts of your deployment for RBAC to ensure Contour has access to Lease and Event objects (this would be the ClusterRole in the provided example YAML).

(#4202, ...

v1.20.0-beta.1

We are delighted to present the first beta for Contour v1.20.0, our layer 7 HTTP reverse proxy for Kubernetes clusters.

Please note that this is pre-release software, and as such we do not recommend installing it in production environments.
Feedback and bug reports are welcome!

Major Changes

Gateway API v1alpha2 support

Contour now exclusively supports Gateway API v1alpha2, the latest available version.
This version of Gateway API has a number of breaking changes, which are detailed in the Gateway API changelog.
Contour currently supports a single GatewayClass and associated Gateway, and HTTPRoutes and TLSRoutes that attach to the Gateway. TCPRoute and UDPRoute are not supported.
For a list of other functionality that remains to be implemented, see Contour's area/gateway-api label.

As part of this change, support for Gateway API v1alpha1 has been dropped, and any v1alpha1 resources will not be automatically converted to v1alpha2 resources because the API has moved to a different API group (from networking.x-k8s.io to gateway.networking.k8s.io).

To get started, see the Contour & Gateway API (v1alpha2) guide.

(#4047, @skriss)

xDS management connection between Contour and Envoy set to TLSv1.3

The minimum accepted TLS version for Contour xDS server is changed from TLSv1.2 to TLSv1.3.
Previously in Contour 1.19, the maximum accepted TLS version for Envoy xDS client was increased to TLSv1.3 which allows it to connect to Contour xDS server using TLSv1.3.

If upgrading from a version prior to Contour 1.19, the old Envoys will be unable to connect to new Contour until also Envoys are upgraded.
Until that, old Envoys are unable to receive new configuration data.

For further information, see Contour architecture and xDS API in Envoy documentation.

(#4065, @tsaarni)

Minor Changes

Metrics over HTTPS

Both Envoy and Contour metrics can now be served over HTTPS.
Server can alternatively also require client to present certificate which is validated against configured CA certificate.
This feature makes it possible to limit the visibility of metrics to authorized clients.

(#3707, @tsaarni)

Performance improvement for processing configuration

The performance of Contour's configuration processing has been made more efficient, particularly for clusters with large numbers (i.e. >1k) of HTTPProxies and/or Ingresses.
This means that there should be less of a delay between creating/updating an HTTPProxy/Ingress in Kubernetes, and having it reflected in Envoy's configuration.

(#4099, @skriss)

Allow retry policy, num retries to be zero

The field, NumRetries (e.g. count), in the RetryPolicy allows for a zero to be
specified, however Contour's internal logic would see that as "undefined"
and set it back to the Envoy default of 1. This would never allow the value of
zero to be set. Users can set the value to be -1 which will represent disabling
the retry count. If not specified or set to zero, then the Envoy default value
of 1 is used.

(#4117, @stevesloka)

Gateway API: implement PathPrefix matching

Contour now implements Gateway API v1alpha2's "path prefix" matching for HTTPRoutes.
This is now the only native form of prefix matching supported by Gateway API, and is a change from v1alpha1.
Path prefix matching means that the prefix specified in an HTTPRoute rule must match entire segments of a request's path in order to match it, rather than just be a string prefix.
For example, the prefix /foo would match a request for the path /foo/bar but not /foobar.
For more information, see the Gateway API documentation.

(#4119, @skriss)

Gateway API: support ReferencePolicy

Contour now supports the ReferencePolicy CRD in Gateway API v1alpha2.
ReferencePolicy enables certain cross-namespace references to be allowed in Gateway API.
The primary use case is to enable routes (e.g. HTTPRoutes, TLSRoutes) to reference backend Services in different namespaces.
When Contour processes a route that references a service in a different namespace, it will check for a ReferencePolicy that applies to the route and service, and if one exists, it will allow the reference.

(#4138, @skriss)

Gateway API: set Gateway Listener status fields

Contour now sets the .status.listeners.supportedKinds and .status.listeners.attachedRoutes fields on Gateways for Gateway API.
The first describes the list of route groups/kinds that the listener supports, and the second captures the total number of routes that are successfully attached to the listener.

(#4160, @skriss)

Set Gateway listener conditions

Contour now sets various Gateway listener conditions as it processes them, including the "Ready", "Detached", and "ResolvedRefs" condition types, to provide more visibility to the user as to whether their listeners are defined correctly or not.

(#4186, @skriss)

Default status on HTTPProxy resources

When a new HTTPProxy is created, if Contour isn't yet running or
functioning properly, then no status is set on the resource.
Defaults of "NotReconciled/Waiting for controller" are now applied
to any new object until an instance of Contour accepts the
object and updates the status.

(#4133, @stevesloka)

Source IP hash based load balancing

Contour users can now configure their load balancing policies on HTTPProxy resources to hash the source IP of a client to ensure consistent routing to a backend service instance. Using this feature combined with header value hashing can implement advanced request routing and session affinity. Note that if you are using a load balancer to front your Envoy deployment, you will need to ensure it preserves client source IP addresses to ensure this feature is effective.

See this page for more details on this feature.

(#4141, @sunjayBhatia)

TLS Certificate validation updates

Contour now allows non-server certificates that do not have a CN or SAN set, which mostly fixes
#2372 and #3889.

TLS documentation has been updated to make the rules for Secrets holding TLS information clearer.

Those rules are:

For certificates that identify a server, they must:

• be kubernetes.io/tls type
• contain tls.crt, and tls.key keys with the server certificate and key respectively.
• have the first certificate in the tls.crt bundle have a CN or SAN field set.

They may:

• have the tls.crt key contain a certificate chain, as long as the first certificate in the chain is the server certificate.
• add a ca.crt key that contains a Certificate Authority (CA) certificate or certificates.

Certificates in the certificate chain that are not server certificates do not need to have a CN or SAN.

For CA secrets, they must:

• be Opaque type
• contain only a ca.crt key, not tls.crt or tls.key

The ca.crt key may contain one or more CA certificates, that do not need to have a CN or SAN.

(#4165, @youngnick)

HTTPProxy TCPProxy service weights are now applied

Previously, Contour did not apply any service weights defined in an HTTPProxy's TCPProxy, and all services were equally weighted.
Now, if those weights are defined, they are applied so traffic is weighted appropriately across the services.
Note that if no TCPProxy service weights are defined, traffic continues to be equally spread across all services.

(#4169, @skriss)

Leader Election Configuration

contour serve leader election configuration via config file has been deprecated.
The preferred way to configure leader election parameters is now via command line flags.
See here for more detail on the new leader election flags.

Note: If you are using the v1alpha1 ContourConfiguration CRD, leader election configuration has been removed from that CRD as well.
Leader election configuration is not something that will be dynamically configurable once Contour implements configuration reloading via that CRD.

(#4171, @sunjayBhatia)

Transition to controller-runtime managed leader election

Contour now utilizes controller-runtime Manager based leader election and coordination of subroutines.
With this change, Contour is also transitioning away from using a ConfigMap for leader election.
In this release, Contour now uses a combination of ConfigMap and Lease object.
A future release will remove usage of the ConfigMap resource for leader election.

This change should be a no-op for most users, however be sure to re-apply the relevant parts of your deployment for RBAC to ensure Contour has access to Lease and Event objects (this would be the ClusterRole in the provided example YAML).

(#4202, @sunjayBhatia)

HTTP Request Redirect Policy

HTTPProxy.Route now has a HTTPRequestRedirectPolicy which allows for routes to specify a RequestRedirectPolicy.
This policy will allow a redirect to be configured for a specific set of Conditions within a single route.
The policy can be configured with a Hostname, StatusCode, Scheme, and Port.

Additionally, Services on a Route are now optional when a request redirect is defined.

(#4201, @stevesloka)

Other Changes

...

Contour v1.18.3

We are delighted to present version 1.18.3 of Contour, our layer 7 HTTP reverse proxy for Kubernetes clusters.

This is a backport release to 1.18, bringing the below change in.

Updates

Allow retry policy, num retries to be disabled

The field, NumRetries (e.g. count), in the RetryPolicy allows for a zero to be
specified, however Contour's internal logic would see that as "undefined"
and set it back to the Envoy default of 1. This would never allow the value of
zero to be set. Users can set the value to be -1 which will represent disabling
the retry count. If not specified or set to zero, then the Envoy default value
of 1 is used.

Contour v1.19.1

We are delighted to present version 1.19.1 of Contour, our layer 7 HTTP reverse proxy for Kubernetes clusters.

Updates

Allow retry policy, num retries to be disabled

The field, NumRetries (e.g. count), in the RetryPolicy allows for a zero to be
specified, however Contour's internal logic would see that as "undefined"
and set it back to the Envoy default of 1. This would never allow the value of
zero to be set. Users can set the value to be -1 which will represent disabling
the retry count. If not specified or set to zero, then the Envoy default value
of 1 is used.

Panic with --root-namespaces flag

Fix panic in Contour startup when using --root-namespaces flag

Contour v1.19.0

We are delighted to present version 1.19.0 of Contour, our layer 7 HTTP reverse proxy for Kubernetes clusters.

Updates

Use unix socket for Envoy admin webpage (#3934)

Moves the Envoy admin interface to use a unix socket by creating a new Envoy listener to expose read only information from Envoy admin page over port 9001 (by default).
This change helps to mitigate a Contour CVE which could possibly allow for an ExternalName service to serve the Envoy Admin interface when not desired.

Also updates shutdown-manager to use new unix socket to begin Envoy draining procedure.

Ingress header policies (#4018)

Enable setting headers on all routes on ingress objects by allowing headers to be configured in the Contour config and applied to PolicyConfig.applyToIngress: true.

Example:

    policy:
      # Default headers to set on all requests
      request-headers:
        set:
          X-Envoy-Hostname: %HOSTNAME%
        applyToIngress: true

Push images to GHCR and Docker Hub in parallel (#4006)

Starts pushing container images to GHCR in addition to Docker Hub.
Images will be pushed to both registries for a period of time, until the Docker Hub push is removed.

Going forward, the examples & quickstart will utilize the GHCR registry with images like: ghcr.io/projectcontour/contour.

Run Envoy as non-root (#4084)

Envoy no longer need to run as root but runs as nobody.

Make shutdown-ready file path configurable (#4084)

The shutdown-ready file path is now configurable, to allow user to optionally set a path that is writable by setting the --ready-file flag on the shutdown-manager.

HTTPProxy Per-Route and Service Cookie Rewriting

Contour now enables users to customize attributes on HTTP Set-Cookie response headers.
Application specific cookies and cookies generated by Contour's "cookie" load balancing strategy can be rewritten either per HTTPProxy Route or Service.
Users can choose to rewrite the Path, Domain, Secure, and SameSite attributes of the Set-Cookie header currently.
These attributes may be things an application may not be able to accurately set, without prior knowledge of how the application is deployed.
For example, if Contour is in use to rewrite the path or hostname of a request before it reaches an application backend, the application may not be able to accurately set the Path and Domain attributes in a Set-Cookie response header.
This feature can be used to apply security settings to ensure browsers treat generated cookies appropriately.
The SameSite and Secure attributes are currently not set by Envoy when it generates the X-Contour-Session-Affinity, but with this feature, users can customize this cookie further.
Future iterations of this feature may provide cookie rewriting configuration directly as part of the cookie load balancing strategy configuration.

Some more documentation and example configuration can be found here.
Also see Contour's CRD API reference for more details.

ContourConfiguration CRD in Alpha

Contour uses a set of flags on the contour serve command as well as a configuration file represented as in a Kubernetes Configmap for further configuration of Contour & Envoy.
It has been difficult to manage the contents of that file (e.g. yaml in a configmap) along with having no way of properly validating that conifguration, so Contour has introduced
a new ContourConfiguration CRD which refactors the current config file along with any missing flags into a new object.
This new config is in an Alpha state while we verify the format of the configuration file along with its validation.

Contour will continue to support the current configuration file for some time, but looking ahead to the roadamp, ContourConfiguration will be the new way to configure Contour.

Additional details around the design of this change can be read in the design doc: https://github.com/projectcontour/contour/blob/main/design/configuration-crd.md

New Changelog process

Contour now requires:

• All PRs be labelled with a release-note/ label, where category is one of major, minor, small, docs, infra, or not-required.
• A changelog file to be created in changelogs/unreleased for each PR, unless the category is not-required. The filename must be PR#-githubID-category, where githubID is that of the person opening the PR, and the category matches the label category.

Gateway API

Support TLSRoute weighted ForwardTos (#3938)

Add support for weighted ForwardTos in TLSRoute rules.
Per spec, weights default to 1 if unspecified, and weights of 0 mean no traffic is forwarded to the backend.

Site

Alt attribute to images (#3917)

Adds alt tags for better web accessibility.

Thanks @johnnycase for contributing this!

Website notice feature (#3955)

Adds site formatting for projectcontour.io to have new "warning", "note", "info", and "tip" notices.

Thanks @gary-tai for contributing this!

Misc

Update security process docs post advisory (#3945)

Updates the security process should a new security advisory be discovered with Contour.

Add threat model and security posture documentation (#4011)

Adds a Security document outlining Contour's threat model and how to report security issues.

Updates for Kubernetes 1.22 (#3953)

Updates Go modules, KinD images, and kubectl version to support Kubernetes 1.22.

Code of Conduct (#4032)

Updates the Code of Conduct to use the CNCF template.

Thanks @mzrithm for contributing this!

Upgrading

Please consult the upgrade documentation.

Compatible Kubernetes Versions

Contour v1.19.0 is tested against Kubernetes 1.20 through 1.22

Community Thanks!

We’re immensely grateful for all the community contributions that help make Contour even better! For this release, special thanks go out to the following contributors:

• @gary-tai
• @senthilnathan
• @mzrithm
• @johnnycase

Are you a Contour user? We would love to know!

If you're using Contour and want to add your organization to our adopters list, please visit this page. 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 GitHub thread.

Contour v1.18.2

We are delighted to present version 1.18.2 of Contour, our layer 7 HTTP reverse proxy for Kubernetes clusters.

Fixes

Performance Fix for Processing Config

#4061 Fixes a performance issue in Contour's config processing. This issue primarily impacted users with very large numbers of HTTPProxies/Ingresses/Services, who were seeing Contour take up to a minute or two to process additional configuration. With this fix, processing times should be significantly improved for users with many resources. See #4058 and #4061 for additional information.

Upgrading

Instructions for upgrading to Contour 1.18.2 can be found here.