Contour v1.27.1

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

All Changes

• Updates Envoy to v1.28.1. See the release notes for v1.28.1 here.

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.27.1 is tested against Kubernetes 1.26 through 1.28.

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

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

All Changes

• Updates Envoy to v1.27.3. See the release notes for v1.27.3 here.

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.26.2 is tested against Kubernetes 1.26 through 1.28.

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.28.0-rc.1

We are delighted to present version v1.28.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/Upgrading
• Compatible Kubernetes Versions
• Community Thanks!

Major Changes

Upstream TLS now supports TLS 1.3 and TLS parameters can be configured

The default maximum TLS version for upstream connections is now 1.3, instead of the Envoy default of 1.2.

In a similar way to how Contour users can configure Min/Max TLS version and
Cipher Suites for Envoy's listeners, users can now specify the
same information for upstream connections. In the ContourConfiguration, this is
available under spec.envoy.cluster.upstreamTLS. The equivalent config file
parameter is cluster.upstream-tls.

(#5828, @KauzClay)

Update to Gateway API 1.0

Contour now uses Gateway API 1.0, which graduates the core resources GatewayClass, Gateway and HTTPRoute to the v1 API version.

For backwards compatibility, this version of Contour continues to watch for v1beta1 versions of these resources, to ease the migration process for users.
However, future versions of Contour will move to watching for v1 versions of these resources.
Note that if you are using Gateway API 1.0 and the v1 API group, the resources you create will also be available from the API server as v1beta1 resources so Contour will correctly reconcile them as well.

(#5898, @skriss)

Support for Gateway API BackendTLSPolicy

The BackendTLSPolicy CRD can now be used with HTTPRoute to configure a Contour gateway to connect to a backend Service with TLS. This will give users the ability to use Gateway API to configure their routes to securely connect to backends that use TLS with Contour.

The BackendTLSPolicy spec requires you to specify a targetRef, which can currently only be a Kubernetes Service within the same namespace as the BackendTLSPolicy. The targetRef is what Service should be watched to apply the BackendTLSPolicy to. A SectionName can also be configured to the port name of a Service to reference a specific section of the Service.

The spec also requires you to specify caCertRefs, which can either be a ConfigMap or Secret with a ca.crt key in the data map containing a PEM-encoded TLS certificate. The CA certificates referenced will be configured to be used by the gateway to perform TLS to the backend Service. You will also need to specify a Hostname, which will be used to configure the SNI the gateway will use for the connection.

See Gateway API's GEP-1897 for the proposal for BackendTLSPolicy.

(#6119, @flawedmatrix and @christianang)

Minor Changes

JWT Authentication happens before External Authorization

Fixes a bug where when the external authorization filter and JWT authentication filter were both configured, the external authorization filter was executed before the JWT authentication filter. Now, JWT authentication happens before external authorization when they are both configured.

(#5840, @izturn)

Allow Multiple SANs in Upstream Validation section of HTTPProxy

This change introduces a max length of 250 characters to the field subjectName in the UpstreamValidation block.

Allow multiple SANs in Upstream Validation by adding a new field subjectNames to the UpstreamValidtion block. This will exist side by side with the previous subjectName field. Using CEL validation, we can enforce that when both are present, the first entry in subjectNames must match the value of subjectName.

(#5849, @KauzClay)

Gateway API Backend Protocol Selection

For Gateway API, Contour now enables end-users to specify backend protocols by setting the backend Service's ServicePort.AppProtocol parameter. The accepted values are kubernetes.io/h2c and kubernetes.io/ws. Note that websocket upgrades are already enabled by default for Gateway API. If AppProtocol is set, any other configurations, such as the annotation: projectcontour.io/upstream-protocol.{protocol} will be disregarded.

(#5934, @izturn)

Gateway API: support HTTPRoute request timeouts

Contour now enables end-users to specify request timeouts by setting the HTTPRouteRule.Timeouts.Request parameter. Note that BackendRequest is not yet implemented because without Gateway API support for retries, it's functionally equivalent to Request.

(#5997, @izturn)

Support for Global Circuit Breaker Policy

The way circuit-breaker-annotations work currently is that when not present they are being defaulted to Envoy defaults. The Envoy defaults can be quite low for larger clusters with more traffic so if a user accidentally deletes them or unset them this cause an issue. With this change we are providing contour administrators the ability to provide global defaults that are good. In that case even if the user forgets to set them or deletes them they can have the safety net of good defaults. They can be configured via cluster.circuit-breakers or via `ContourConfiguration`` CRD in spec.envoy.cluster.circuitBreakers

(#6013, @davinci26)

Allow setting connection limit per listener

Adds a listeners.max-connections-per-listener config option to Contour config file and spec.envoy.listener.maxConnectionsPerListener to the ContourConfiguration CRD.

Setting the max connection limit per listener field limits the number of active connections to a listener. The default, if unset, is unlimited.

(#6058, @flawedmatrix)

Upstream TLS validation and client certificate for TCPProxy

TCPProxy now supports validating server certificate and using client certificate for upstream TLS connections.
Set httpproxy.spec.tcpproxy.services.validation.caSecret and subjectName to enable optional validation and tls.envoy-client-certificate configuration file field or ContourConfiguration.spec.envoy.clientCertificate to set the optional client certificate.

(#6079, @tsaarni)

Remove Contour container readiness probe initial delay

The Contour Deployment Contour server container previously had its readiness probe initialDelaySeconds field set to 15.
This has been removed from the example YAML manifests and Gateway Provisioner generated Contour Deployment since as of PR #5672 Contour's xDS server will not start or serve any configuration (and the readiness probe will not succeed) until the existing state of the cluster is synced.
In clusters with few resources this will improve the Contour Deployment's update/rollout time as initial startup time should be low.

(#6099, @sunjayBhatia)

Other Changes

• For Gateway API v1.0, the successful attachment of a Route to a Listener is based solely on the combination of the AllowedRoutes field on the corresponding Listener and the Route's ParentRefs field. (#5961, @izturn)
• Gateway API: adds support for Gateway infrastructure labels and annotations``. (#5968, @skriss)
• Gateway API: add the gateway.networking.k8s.io/gateway-name label to generated resources. (#5969, @skriss)
• Fixes a bug with the envoy xDS server where at startup, xDS configuration would not be generated and served until a subsequent configuration change. (#5972, @skriss)
• Envoy: Adds support for setting per-host circuit breaker max-connections threshold using a new service-level annotation: projectcontour.io/per-host-max-connections. (#6016, @relu)
• Updates to Kubernetes 1.29. Supported/tested Kubernetes versions are now 1.27, 1.28 and 1.29. (#6031, @skriss)
• Remove static base runtime layer from bootstrap (#6063, @lubronzhan)
• Updates to Go 1.21.6. See the Go release notes for more information. (#6070, @sunjayBhatia)
• Allow gatewayProvisioner to create contour that only watch limited namespaces of resources (#6073, @lubronzhan)
• Access Log: Contour excludes empty fields in Envoy JSON based access logs by default. (#6077, @abbas-gheydi)
• Updates Envoy to v1.29.0. See the release notes here. (#6123, @skriss)
• Updates HTTP filter names to match between the HTTP connection manager and per-filter config on virtual hosts/routes, and to use canonical names. (#6124, @skriss)
• Gateway API provisioner now checks gateway.networking.k8s.io/bundle-version annotation on Gateway CRDs and sets SupportedVersion status condition on GatewayClass if annotation value matches supported Gateway API version. Best-effort support is provided if version does not match. (#6147, @sunjayBhatia)

Docs Changes

• Document that Gateway names ...

Contour v1.27.0

We are delighted to present version v1.27.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

Fix bug with algorithm used to sort Envoy regex/prefix path rules

Envoy greedy matches routes and as a result the order route matches are presented to Envoy is important. Contour attempts to produce consistent routing tables so that the most specific route matches are given preference. This is done to facilitate consistency when using HTTPProxy inclusion and provide a uniform user experience for route matching to be inline with Ingress and Gateway API Conformance.

This changes fixes the sorting algorithm used for Prefix and Regex based path matching. Previously the algorithm lexicographically sorted based on the path match string instead of sorting them based on the length of the Prefix|Regex. i.e. Longer prefix/regexes will be sorted first in order to give preference to more specific routes, then lexicographic sorting for things of the same length.

Note that for prefix matching, this change is not expected to change the relative ordering of more specific prefixes vs. less specific ones when the more specific prefix match string has the less specific one as a prefix, e.g. /foo/bar will continue to sort before /foo. However, relative ordering of other combinations of prefix matches may change per the above description.

How to update safely

Caution is advised if you update Contour and you are operating large routing tables. We advise you to:

1. Deploy a duplicate Contour installation that parses the same CRDs
2. Port-forward to the Envoy admin interface docs
3. Access http://127.0.0.1:9001/config_dump and compare the configuration of Envoy. In particular the routes and their order. The prefix routes might be changing in order, so if they are you need to verify that the route matches as expected.

(#5752, @davinci26)

Minor Changes

Specific routes can now opt out of the virtual host's global rate limit policy

Setting rateLimitPolicy.global.disabled flag to true on a specific route now disables the global rate limit policy inherited from the virtual host for that route.

Sample Configurations

In the example below, /foo route is opted out from the global rate limit policy defined by the virtualhost.

httpproxy.yaml

apiVersion: projectcontour.io/v1
kind: HTTPProxy
metadata:
  name: echo
spec:
  virtualhost:
    fqdn: local.projectcontour.io
    rateLimitPolicy:
      global:
        descriptors:
          - entries:
            - remoteAddress: {}
            - genericKey:
                key: vhost
                value: local.projectcontour.io
  routes:
    - conditions:
        - prefix: /
      services:
        - name: ingress-conformance-echo
          port: 80
    - conditions:
        - prefix: /foo
      rateLimitPolicy:
        global:
          disabled: true
      services:
        - name: ingress-conformance-echo
          port: 80

(#5657, @shadialtarsha)

Contour now waits for the cache sync before starting the DAG rebuild and XDS server

Before this, we only waited for informer caches to sync but didn't wait for delivering the events to subscribed handlers.
Now contour waits for the initial list of Kubernetes objects to be cached and processed by handlers (using the returned HasSynced methods)
and then starts building its DAG and serving XDS.

(#5672, @therealak12)

HTTPProxy: Allow Host header rewrite with dynamic headers.

This Change allows the host header to be rewritten on requests using dynamic headers on the only route level.

Example

apiVersion: projectcontour.io/v1
kind: HTTPProxy
metadata:
  name: dynamic-host-header-rewrite
spec:
  fqdn: local.projectcontour.io
  routes:
    - conditions:
      - prefix: /
      services:
        - name: s1
          port: 80
    - requestHeaderPolicy:
        set:
        - name: host
          value: "%REQ(x-rewrite-header)%"

(#5678, @clayton-gonsalves)

Add Kubernetes Endpoint Slice support

This change optionally enables Contour to consume the kubernetes endpointslice API to determine the endpoints to configure Envoy with.
Note: This change is off by default and is gated by the feature flag useEndpointSlices.

This feature will be enabled by default in a future version on Contour once it has had sufficient bake time in production environments.

(#5745, @clayton-gonsalves)

Max HTTP requests per IO cycle is configurable as an additional mitigation for HTTP/2 CVE-2023-44487

Envoy v1.27.1 mitigates CVE-2023-44487 with some default runtime settings, however the http.max_requests_per_io_cycle does not have a default value.
This change allows configuring this runtime setting via Contour configuration to allow administrators of Contour to prevent abusive connections from starving resources from other valid connections.
The default is left as the existing behavior (no limit) so as not to impact existing valid traffic.

The Contour ConfigMap can be modified similar to the following (and Contour restarted) to set this value:

listener:
  max-requests-per-io-cycle: 10

(Note this can be used in addition to the existing Listener configuration field listener.max-requests-per-connection which is used primarily for HTTP/1.1 connections and is an approximate limit for HTTP/2)

See the Envoy release notes for more details.

(#5827, @sunjayBhatia)

HTTP/2 max concurrent streams is configurable

This field can be used to limit the number of concurrent streams Envoy will allow on a single connection from a downstream peer.
It can be used to tune resource usage and as a mitigation for DOS attacks arising from vulnerabilities like CVE-2023-44487.

The Contour ConfigMap can be modified similar to the following (and Contour restarted) to set this value:

listener:
  http2-max-concurrent-streams: 50

(#5850, @sunjayBhatia)

Other Changes

• Add flags: --incluster, --kubeconfig for enable run the gateway-provisioner in or out of the cluster. (#5686, @izturn)
• Gateway provisioner: Add the overloadMaxHeapSize configuration option to contourDeployment to allow adding overloadManager configuration when generating envoy's initial configuration file. (#5699, @yangyy93)
• Drops the Gateway API webhook from example manifests and testing since validations are now implemented in Common Expression Language (CEL). (#5735, @skriss)
• Gateway API: set Listeners' ResolvedRefs condition to true by default. (#5804, @skriss)
• Updates to Go 1.21.3. See the Go release notes for more information. (#5841, @sunjayBhatia)
• Updates Envoy to v1.28.0. See the release notes here. (#5870, @skriss)

Docs Changes

• Switch to documenting the Gateway API release semantic version instead of API versions in versions.yaml and the compatibility matrix, to provide more information about features available with each release. (#5871, @skriss)

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.27.0 is tested against Kubernetes 1.26 through 1.28.

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:

• @clayton-gonsalves
• @davinci26
• @izturn
• @shadialtarsha
• @therealak12
• @yangyy93

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.27.0-rc.1

We are delighted to present version v1.27.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

Fix bug with algorithm used to sort Envoy regex/prefix path rules

Envoy greedy matches routes and as a result the order route matches are presented to Envoy is important. Contour attempts to produce consistent routing tables so that the most specific route matches are given preference. This is done to facilitate consistency when using HTTPProxy inclusion and provide a uniform user experience for route matching to be inline with Ingress and Gateway API Conformance.

This changes fixes the sorting algorithm used for Prefix and Regex based path matching. Previously the algorithm lexicographically sorted based on the path match string instead of sorting them based on the length of the Prefix|Regex. i.e. Longer prefix/regexes will be sorted first in order to give preference to more specific routes, then lexicographic sorting for things of the same length.

Note that for prefix matching, this change is not expected to change the relative ordering of more specific prefixes vs. less specific ones when the more specific prefix match string has the less specific one as a prefix, e.g. /foo/bar will continue to sort before /foo. However, relative ordering of other combinations of prefix matches may change per the above description.

How to update safely

Caution is advised if you update Contour and you are operating large routing tables. We advise you to:

1. Deploy a duplicate Contour installation that parses the same CRDs
2. Port-forward to the Envoy admin interface docs
3. Access http://127.0.0.1:9001/config_dump and compare the configuration of Envoy. In particular the routes and their order. The prefix routes might be changing in order, so if they are you need to verify that the route matches as expected.

(#5752, @davinci26)

Minor Changes

Specific routes can now opt out of the virtual host's global rate limit policy

Setting rateLimitPolicy.global.disabled flag to true on a specific route now disables the global rate limit policy inherited from the virtual host for that route.

Sample Configurations

In the example below, /foo route is opted out from the global rate limit policy defined by the virtualhost.

httpproxy.yaml

apiVersion: projectcontour.io/v1
kind: HTTPProxy
metadata:
  name: echo
spec:
  virtualhost:
    fqdn: local.projectcontour.io
    rateLimitPolicy:
      global:
        descriptors:
          - entries:
            - remoteAddress: {}
            - genericKey:
                key: vhost
                value: local.projectcontour.io
  routes:
    - conditions:
        - prefix: /
      services:
        - name: ingress-conformance-echo
          port: 80
    - conditions:
        - prefix: /foo
      rateLimitPolicy:
        global:
          disabled: true
      services:
        - name: ingress-conformance-echo
          port: 80

(#5657, @shadialtarsha)

Contour now waits for the cache sync before starting the DAG rebuild and XDS server

Before this, we only waited for informer caches to sync but didn't wait for delivering the events to subscribed handlers.
Now contour waits for the initial list of Kubernetes objects to be cached and processed by handlers (using the returned HasSynced methods)
and then starts building its DAG and serving XDS.

(#5672, @therealak12)

HTTPProxy: Allow Host header rewrite with dynamic headers.

This Change allows the host header to be rewritten on requests using dynamic headers on the only route level.

Example

apiVersion: projectcontour.io/v1
kind: HTTPProxy
metadata:
  name: dynamic-host-header-rewrite
spec:
  fqdn: local.projectcontour.io
  routes:
    - conditions:
      - prefix: /
      services:
        - name: s1
          port: 80
    - requestHeaderPolicy:
        set:
        - name: host
          value: "%REQ(x-rewrite-header)%"

(#5678, @clayton-gonsalves)

Add Kubernetes Endpoint Slice support

This change optionally enables Contour to consume the kubernetes endpointslice API to determine the endpoints to configure Envoy with.
Note: This change is off by default and is gated by the feature flag useEndpointSlices.

This feature will be enabled by default in a future version on Contour once it has had sufficient bake time in production environments.

(#5745, @clayton-gonsalves)

Max HTTP requests per IO cycle is configurable as an additional mitigation for HTTP/2 CVE-2023-44487

Envoy v1.27.1 mitigates CVE-2023-44487 with some default runtime settings, however the http.max_requests_per_io_cycle does not have a default value.
This change allows configuring this runtime setting via Contour configuration to allow administrators of Contour to prevent abusive connections from starving resources from other valid connections.
The default is left as the existing behavior (no limit) so as not to impact existing valid traffic.

The Contour ConfigMap can be modified similar to the following (and Contour restarted) to set this value:

listener:
  max-requests-per-io-cycle: 10

(Note this can be used in addition to the existing Listener configuration field listener.max-requests-per-connection which is used primarily for HTTP/1.1 connections and is an approximate limit for HTTP/2)

See the Envoy release notes for more details.

(#5827, @sunjayBhatia)

HTTP/2 max concurrent streams is configurable

This field can be used to limit the number of concurrent streams Envoy will allow on a single connection from a downstream peer.
It can be used to tune resource usage and as a mitigation for DOS attacks arising from vulnerabilities like CVE-2023-44487.

The Contour ConfigMap can be modified similar to the following (and Contour restarted) to set this value:

listener:
  http2-max-concurrent-streams: 50

(#5850, @sunjayBhatia)

Other Changes

• Add flags: --incluster, --kubeconfig for enable run the gateway-provisioner in or out of the cluster. (#5686, @izturn)
• Gateway provisioner: Add the overloadMaxHeapSize configuration option to contourDeployment to allow adding overloadManager configuration when generating envoy's initial configuration file. (#5699, @yangyy93)
• Drops the Gateway API webhook from example manifests and testing since validations are now implemented in Common Expression Language (CEL). (#5735, @skriss)
• Gateway API: set Listeners' ResolvedRefs condition to true by default. (#5804, @skriss)
• Updates to Go 1.21.3. See the Go release notes for more information. (#5841, @sunjayBhatia)
• Updates Envoy to v1.28.0. See the release notes here. (#5870, @skriss)

Docs Changes

• Switch to documenting the Gateway API release semantic version instead of API versions in versions.yaml and the compatibility matrix, to provide more information about features available with each release. (#5871, @skriss)

Deprecation and Removal Notices

Installing and Upgrading

The simplest way to install v1.27.0-rc.1 is to apply one of the example configurations:

With Gateway API:

kubectl apply -f https://raw.githubusercontent.com/projectcontour/contour/v1.27.0-rc.1/examples/render/contour-gateway.yaml

Without Gateway API:

kubectl apply -f https://raw.githubusercontent.com/projectcontour/contour/v1.27.0-rc.1/examples/render/contour.yaml

Compatible Kubernetes Versions

Contour v1.27.0-rc.1 is tested against Kubernetes 1.26 through 1.28.

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:

• @clayton-gonsalves
• @davinci26
• @izturn
• @shadialtarsha
• @therealak12
• @yangyy93

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

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

• All Changes
• Installing/Upgrading
• Compatible Kubernetes Versions

All Changes

This release includes various dependency bumps and fixes for CVE-2023-44487, including:

• Updates Envoy to v1.27.2. See the release notes for v1.27.1 here and v1.27.2 here.
• Update to Go v1.20.10. See the Go release notes for more information.

Additional mitigations have been added for CVE-2023-44487 in the form of new configuration fields:

Max HTTP requests per IO cycle is configurable as an additional mitigation for HTTP/2 CVE-2023-44487

Envoy mitigates CVE-2023-44487 with some default runtime settings, however the http.max_requests_per_io_cycle does not have a default value.
This change allows configuring this runtime setting via Contour configuration to allow administrators of Contour to prevent abusive connections from starving resources from other valid connections.
The default is left as the existing behavior (no limit) so as not to impact existing valid traffic.

The Contour ConfigMap can be modified similar to the following (and Contour restarted) to set this value:

listener:
  max-requests-per-io-cycle: 10

(Note this can be used in addition to the existing Listener configuration field listener.max-requests-per-connection which is used primarily for HTTP/1.1 connections and is an approximate limit for HTTP/2)

HTTP/2 max concurrent streams is configurable

This field can be used to limit the number of concurrent streams Envoy will allow on a single connection from a downstream peer.
It can be used to tune resource usage and as a mitigation for DOS attacks arising from vulnerabilities like CVE-2023-44487.

The Contour ConfigMap can be modified similar to the following (and Contour restarted) to set this value:

listener:
  http2-max-concurrent-streams: 50

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.26.1 is tested against Kubernetes 1.26 through 1.28.

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

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

• All Changes
• Installing/Upgrading
• Compatible Kubernetes Versions

All Changes

This release includes various dependency bumps and fixes for CVE-2023-44487, including:

• Update to Envoy v1.26.6. See the release notes for v1.26.5 here and v1.26.6 here.
• Update to Go v1.20.10. See the Go release notes for more information.

Additional mitigations have been added for CVE-2023-44487 in the form of new configuration fields:

Max HTTP requests per IO cycle is configurable as an additional mitigation for HTTP/2 CVE-2023-44487

Envoy mitigates CVE-2023-44487 with some default runtime settings, however the http.max_requests_per_io_cycle does not have a default value.
This change allows configuring this runtime setting via Contour configuration to allow administrators of Contour to prevent abusive connections from starving resources from other valid connections.
The default is left as the existing behavior (no limit) so as not to impact existing valid traffic.

The Contour ConfigMap can be modified similar to the following (and Contour restarted) to set this value:

listener:
  max-requests-per-io-cycle: 10

(Note this can be used in addition to the existing Listener configuration field listener.max-requests-per-connection which is used primarily for HTTP/1.1 connections and is an approximate limit for HTTP/2)

HTTP/2 max concurrent streams is configurable

This field can be used to limit the number of concurrent streams Envoy will allow on a single connection from a downstream peer.
It can be used to tune resource usage and as a mitigation for DOS attacks arising from vulnerabilities like CVE-2023-44487.

The Contour ConfigMap can be modified similar to the following (and Contour restarted) to set this value:

listener:
  http2-max-concurrent-streams: 50

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.25.3 is tested against Kubernetes 1.25 through 1.27.

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

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

• All Changes
• Installing/Upgrading
• Compatible Kubernetes Versions

All Changes

This release includes various dependency bumps and fixes for CVE-2023-44487, including:

• Update to Envoy v1.25.11. See the release notes for v1.25.10 here and v1.25.11 here.
• Update to Go v1.20.10. See the Go release notes for more information.

Additional mitigations have been added for CVE-2023-44487 in the form of new configuration fields:

Max HTTP requests per IO cycle is configurable as an additional mitigation for HTTP/2 CVE-2023-44487

Envoy mitigates CVE-2023-44487 with some default runtime settings, however the http.max_requests_per_io_cycle does not have a default value.
This change allows configuring this runtime setting via Contour configuration to allow administrators of Contour to prevent abusive connections from starving resources from other valid connections.
The default is left as the existing behavior (no limit) so as not to impact existing valid traffic.

The Contour ConfigMap can be modified similar to the following (and Contour restarted) to set this value:

listener:
  max-requests-per-io-cycle: 10

(Note this can be used in addition to the existing Listener configuration field listener.max-requests-per-connection which is used primarily for HTTP/1.1 connections and is an approximate limit for HTTP/2)

HTTP/2 max concurrent streams is configurable

This field can be used to limit the number of concurrent streams Envoy will allow on a single connection from a downstream peer.
It can be used to tune resource usage and as a mitigation for DOS attacks arising from vulnerabilities like CVE-2023-44487.

The Contour ConfigMap can be modified similar to the following (and Contour restarted) to set this value:

listener:
  http2-max-concurrent-streams: 50

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.24.6 is tested against Kubernetes 1.24 through 1.26.

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

We are delighted to present version v1.26.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

Support for Gateway Listeners on more than two ports

Contour now supports Gateway Listeners with many different ports.
Previously, Contour only allowed a single port for HTTP, and a single port for HTTPS/TLS.

As an example, the following Gateway, with two HTTP ports and two HTTPS ports, is now fully supported:

kind: Gateway
apiVersion: gateway.networking.k8s.io/v1beta1
metadata:
  name: contour
spec:
  gatewayClassName: contour
  listeners:
    - name: http-1
      protocol: HTTP
      port: 80
      allowedRoutes:
        namespaces:
          from: Same
    - name: http-2
      protocol: HTTP
      port: 81
      allowedRoutes:
        namespaces:
          from: Same
    - name: https-1
      protocol: HTTPS
      port: 443
      allowedRoutes:
        namespaces:
          from: Same
      tls:
        mode: Terminate
        certificateRefs:
        - name: tls-cert-1
    - name: https-2
      protocol: HTTPS
      port: 444
      allowedRoutes:
        namespaces:
          from: Same
      tls:
        mode: Terminate
        certificateRefs:
        - name: tls-cert-2

If you are using the Contour Gateway Provisioner, ports for all valid Listeners will automatically be exposed via the Envoy service, and will update when any Listener changes are made.
If you are using static provisioning, you must keep the Service definition in sync with the Gateway spec manually.

Note that if you are using the Contour Gateway Provisioner along with HTTPProxy or Ingress for routing, then your Gateway must have exactly one HTTP Listener and one HTTPS Listener.
For this case, Contour supports a custom HTTPS Listener protocol value, to avoid having to specify TLS details in the Listener (since they're specified in the HTTPProxy or Ingress instead):

kind: Gateway
apiVersion: gateway.networking.k8s.io/v1beta1
metadata:
  name: contour-with-httpproxy
spec:
  gatewayClassName: contour
  listeners:
    - name: http
      protocol: HTTP
      port: 80
      allowedRoutes:
        namespaces:
          from: All
    - name: https
      protocol: projectcontour.io/https
      port: 443
      allowedRoutes:
        namespaces:
          from: All

(#5160, @skriss)

Minor Changes

Contour now outputs metrics about status update load

Metrics on status update counts and duration are now output by the xDS server.
This should enable deployments at scale to diagnose delays in status updates and possibly tune the --kubernetes-client-qps and --kubernetes-client-burst flags.

(#5037, @sunjayBhatia)

Watching specific namespaces

The contour serve command takes a new optional flag, --watch-namespaces, that can
be used to restrict the namespaces where the Contour instance watches for resources.
Consequently, resources in other namespaces will not be known to Contour and will not
be acted upon.

You can watch a single or multiple namespaces, and you can further restrict the root
namespaces with --root-namespaces just like before. Root namespaces must be a subset
of the namespaces being watched, for example:

--watch-namespaces=my-admin-namespace,my-app-namespace --root-namespaces=my-admin-namespace

If the --watch-namespaces flag is not used, then all namespaces will be watched by default.

(#5214, @nsimons)

HTTPProxy: Implement Regex Path Matching and Regex Header Matching.

This Change Adds 2 features to HTTPProxy

1. Regex based path matching.
2. Regex based header matching.

Path Matching

In addition to prefix and exact, HTTPProxy now also support regex.

Root Proxies

apiVersion: projectcontour.io/v1
kind: HTTPProxy
metadata:
  name: root-regex-match
spec:
  fqdn: local.projectcontour.io
  routes:
    - conditions:
      # matches
      # - /list/1234
      # - /list/
      # - /list/foobar
      # and so on and so forth
      - regex: /list/.*
      services:
        - name: s1
          port: 80
    - conditions:
      # matches
      # - /admin/dev
      # - /admin/prod
      - regex: /admin/(prod|dev)
      services:
        - name: s2
          port: 80

Inclusion

Root

apiVersion: projectcontour.io/v1
kind: HTTPProxy
metadata:
  name: root-regex-match
spec:
  fqdn: local.projectcontour.io
  includes:
  - name: child-regex-match
    conditions:
    - prefix: /child
  routes:
    - conditions:
      - prefix: /
      services:
        - name: s1
          port: 80

Included

apiVersion: projectcontour.io/v1
kind: HTTPProxy
metadata:
  name: child-regex-match
spec:
  fqdn: local.projectcontour.io
  routes:
    - conditions:
      # matches
      # - /child/list/1234
      # - /child/list/
      # - /child/list/foobar
      # and so on and so forth
      - regex: /list/.*
      services:
        - name: s1
          port: 80
    - conditions:
      # matches
      # - /child/admin/dev
      # - /child/admin/prod
      - regex: /admin/(prod|dev)
      services:
        - name: s2
          port: 80
    - conditions:
      # matches
      # - /child/bar/stats
      # - /child/foo/stats
      # and so on and so forth
      - regex: /.*/stats
      services:
        - name: s3
          port: 80

Header Regex Matching

apiVersion: projectcontour.io/v1
kind: HTTPProxy
metadata:
  name: httpproxy-header-matching
spec:
  fqdn: local.projectcontour.io
  routes:
    - conditions:
      - queryParam:
          # matches header `x-header` with value of `dev-value` or `prod-value`
           name: x-header
          regex: (dev|prod)-value
      services:
        - name: s4
          port: 80

(#5319, @clayton-gonsalves)

Adds critical level for access logging

New critical access log level was introduced to reduce the volume of logs for busy installations. Critical level produces access logs for response status >= 500.

(#5360, @davinci26)

Default Global RateLimit Policy

This Change adds the ability to define a default global rate limit policy in the Contour configuration
to be used as a global rate limit policy by all HTTPProxy objects.
HTTPProxy object can decide to opt out and disable this feature using disabled config.

Sample Configurations

contour.yaml

apiVersion: v1
kind: ConfigMap
metadata:
  name: contour
  namespace: projectcontour
data:
  contour.yaml: |
    rateLimitService:
      extensionService: projectcontour/ratelimit
      domain: contour
      failOpen: false
      defaultGlobalRateLimitPolicy:
        descriptors:
          - entries:
              - remoteAddress: {}
          - entries:
              - genericKey:
                  value: foo

(#5363, @shadialtarsha)

Contour supports setting the MaxRequestsPerConnection

Support setting of MaxRequestsPerConnection on listeners or clusters via the contour configuration.

(#5417, @clayton-gonsalves)

Failures to automatically set GOMAXPROCS are no longer fatal

In some (particularly local development) environments the automaxprocs library fails due to the cgroup namespace setup.
This failure is no longer fatal for Contour.
Contour will now simply log the error and continue with the automatic GOMAXPROCS detection ignored.

(#5427, @sunjayBhatia)

Routes with HTTP Method matching have higher precedence

For conformance with Gateway API v0.7.1+, routes that utilize HTTP method matching now have an explicit precedence over routes with header/query matches.
See the Gateway API documentation for a description of this precedence order.

This change applies not only to HTTPRoute but also HTTPProxy method matches (implemented in configuration via a header match on the :method header).

(#5434, @sunjayBhatia)

Host header including port is passed through unmodified to backend

Previously Contour would strip any port from the Host header in a downstream request for convenience in routing.
This resulted in backends not receiving the Host header with a port.
We no longer do this, for conformance with Gateway API (this change also applies to HTTPProxy and Ingress configuration).

(#5437, @sunjayBhatia)

Gateway API: add TCPRoute support

Contour now supports Gateway API's TCPRoute resource.
This route type provides simple TCP forwarding for traffic received on a given Listener port.

This is a simple example of a Gateway and TCPRoute configuration:

kind: Gateway
apiVersion: gateway.networking.k8s.io/v1beta1
metadata:
  name: contour
  namespace: projectcontour
spec:
  gatewayClassName: contour
  listeners:
    - name: tcp-listener
      protocol: TCP
      port: 10000
      allowedRoutes:
        namespaces:
          from: All
---
apiVersion: gateway.networking.k8s.io/v1alpha2
kind: TCPRoute
metadata:
  name: echo-1
  namespace: default
spec:
  parentRefs:
  - namespace: projectcontour
    name: contour
    sectionName: tcp-listener
  rules:
  - backendRefs:
    - name: s1
      port: 80

(#5471, @skriss)
...

Contour v1.26.0-rc.1

We are delighted to present version v1.26.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/Upgrading
• Compatible Kubernetes Versions
• Community Thanks!

Major Changes

Support for Gateway Listeners on more than two ports

Contour now supports Gateway Listeners with many different ports.
Previously, Contour only allowed a single port for HTTP, and a single port for HTTPS/TLS.

As an example, the following Gateway, with two HTTP ports and two HTTPS ports, is now fully supported:

kind: Gateway
apiVersion: gateway.networking.k8s.io/v1beta1
metadata:
  name: contour
spec:
  gatewayClassName: contour
  listeners:
    - name: http-1
      protocol: HTTP
      port: 80
      allowedRoutes:
        namespaces:
          from: Same
    - name: http-2
      protocol: HTTP
      port: 81
      allowedRoutes:
        namespaces:
          from: Same
    - name: https-1
      protocol: HTTPS
      port: 443
      allowedRoutes:
        namespaces:
          from: Same
      tls:
        mode: Terminate
        certificateRefs:
        - name: tls-cert-1
    - name: https-2
      protocol: HTTPS
      port: 444
      allowedRoutes:
        namespaces:
          from: Same
      tls:
        mode: Terminate
        certificateRefs:
        - name: tls-cert-2

If you are using the Contour Gateway Provisioner, ports for all valid Listeners will automatically be exposed via the Envoy service, and will update when any Listener changes are made.
If you are using static provisioning, you must keep the Service definition in sync with the Gateway spec manually.

Note that if you are using the Contour Gateway Provisioner along with HTTPProxy or Ingress for routing, then your Gateway must have exactly one HTTP Listener and one HTTPS Listener.
For this case, Contour supports a custom HTTPS Listener protocol value, to avoid having to specify TLS details in the Listener (since they're specified in the HTTPProxy or Ingress instead):

kind: Gateway
apiVersion: gateway.networking.k8s.io/v1beta1
metadata:
  name: contour-with-httpproxy
spec:
  gatewayClassName: contour
  listeners:
    - name: http
      protocol: HTTP
      port: 80
      allowedRoutes:
        namespaces:
          from: All
    - name: https
      protocol: projectcontour.io/https
      port: 443
      allowedRoutes:
        namespaces:
          from: All

(#5160, @skriss)

Minor Changes

Contour now outputs metrics about status update load

Metrics on status update counts and duration are now output by the xDS server.
This should enable deployments at scale to diagnose delays in status updates and possibly tune the --kubernetes-client-qps and --kubernetes-client-burst flags.

(#5037, @sunjayBhatia)

Watching specific namespaces

The contour serve command takes a new optional flag, --watch-namespaces, that can
be used to restrict the namespaces where the Contour instance watches for resources.
Consequently, resources in other namespaces will not be known to Contour and will not
be acted upon.

You can watch a single or multiple namespaces, and you can further restrict the root
namespaces with --root-namespaces just like before. Root namespaces must be a subset
of the namespaces being watched, for example:

--watch-namespaces=my-admin-namespace,my-app-namespace --root-namespaces=my-admin-namespace

If the --watch-namespaces flag is not used, then all namespaces will be watched by default.

(#5214, @nsimons)

HTTPProxy: Implement Regex Path Matching and Regex Header Matching.

This Change Adds 2 features to HTTPProxy

1. Regex based path matching.
2. Regex based header matching.

Path Matching

In addition to prefix and exact, HTTPProxy now also support regex.

Root Proxies

apiVersion: projectcontour.io/v1
kind: HTTPProxy
metadata:
  name: root-regex-match
spec:
  fqdn: local.projectcontour.io
  routes:
    - conditions:
      # matches
      # - /list/1234
      # - /list/
      # - /list/foobar
      # and so on and so forth
      - regex: /list/.*
      services:
        - name: s1
          port: 80
    - conditions:
      # matches
      # - /admin/dev
      # - /admin/prod
      - regex: /admin/(prod|dev)
      services:
        - name: s2
          port: 80

Inclusion

Root

apiVersion: projectcontour.io/v1
kind: HTTPProxy
metadata:
  name: root-regex-match
spec:
  fqdn: local.projectcontour.io
  includes:
  - name: child-regex-match
    conditions:
    - prefix: /child
  routes:
    - conditions:
      - prefix: /
      services:
        - name: s1
          port: 80

Included

apiVersion: projectcontour.io/v1
kind: HTTPProxy
metadata:
  name: child-regex-match
spec:
  fqdn: local.projectcontour.io
  routes:
    - conditions:
      # matches
      # - /child/list/1234
      # - /child/list/
      # - /child/list/foobar
      # and so on and so forth
      - regex: /list/.*
      services:
        - name: s1
          port: 80
    - conditions:
      # matches
      # - /child/admin/dev
      # - /child/admin/prod
      - regex: /admin/(prod|dev)
      services:
        - name: s2
          port: 80
    - conditions:
      # matches
      # - /child/bar/stats
      # - /child/foo/stats
      # and so on and so forth
      - regex: /.*/stats
      services:
        - name: s3
          port: 80

Header Regex Matching

apiVersion: projectcontour.io/v1
kind: HTTPProxy
metadata:
  name: httpproxy-header-matching
spec:
  fqdn: local.projectcontour.io
  routes:
    - conditions:
      - queryParam:
          # matches header `x-header` with value of `dev-value` or `prod-value`
           name: x-header
          regex: (dev|prod)-value
      services:
        - name: s4
          port: 80

(#5319, @clayton-gonsalves)

Support Gateway API v0.7.1

Contour now supports Gateway API v0.7.1, keeping up to date with conformance and API changes.
This release mainly contains refinements to status conditions and conformance test additions.
See v0.7.0 release notes and v0.7.1 release notes .

(#5353, @sunjayBhatia)

Adds critical level for access logging

New critical access log level was introduced to reduce the volume of logs for busy installations. Critical level produces access logs for response status >= 500.

(#5360, @davinci26)

Default Global RateLimit Policy

This Change adds the ability to define a default global rate limit policy in the Contour configuration
to be used as a global rate limit policy by all HTTPProxy objects.
HTTPProxy object can decide to opt out and disable this feature using disabled config.

Sample Configurations

contour.yaml

apiVersion: v1
kind: ConfigMap
metadata:
  name: contour
  namespace: projectcontour
data:
  contour.yaml: |
    rateLimitService:
      extensionService: projectcontour/ratelimit
      domain: contour
      failOpen: false
      defaultGlobalRateLimitPolicy:
        descriptors:
          - entries:
              - remoteAddress: {}
          - entries:
              - genericKey:
                  value: foo

(#5363, @shadialtarsha)

Contour supports setting the MaxRequestsPerConnection

Support setting of MaxRequestsPerConnection on listeners or clusters via the contour configuration.

(#5417, @clayton-gonsalves)

Failures to automatically set GOMAXPROCS are no longer fatal

In some (particularly local development) environments the automaxprocs library fails due to the cgroup namespace setup.
This failure is no longer fatal for Contour.
Contour will now simply log the error and continue with the automatic GOMAXPROCS detection ignored.

(#5427, @sunjayBhatia)

Routes with HTTP Method matching have higher precedence

For conformance with Gateway API v0.7.1+, routes that utilize HTTP method matching now have an explicit precedence over routes with header/query matches.
See the Gateway API documentation for a description of this precedence order.

This change applies not only to HTTPRoute but also HTTPProxy method matches (implemented in configuration via a header match on the :method header).

(#5434, @sunjayBhatia)

Host header including port is passed through unmodified to backend

Previously Contour would strip any port from the Host header in a downstream request for convenience in routing.
This resulted in backends not receiving the Host header with a port.
We no longer do this, for conformance with Gateway API (this change also applies to HTTPProxy and Ingress configuration).

(#5437, @sunjayBhatia)

Gateway API: add TCPRoute support

Contour now supports Gateway API's TCPRoute resource.
This route type provides simple TCP forwarding for traffic received on a given Listener port.

This is a simple example of a Gateway and TCPRoute configuration:
...