Contour v0.10.0 release candidate 1

v0.10.0-rc.1

contour 0.10.0 release candidate 1

Contour v0.9.0

Heptio is proud to present version 0.9 of Contour, our Envoy powered Kubernetes Ingress Controller. It is recommended that all users upgrade to Contour 0.9.

New and improved

Improved support for TCP proxying

Contour 0.9 adds support for terminating the TLS encapsulated TCP session at the backend service, not Contour's edge. Otherwise known as TLS passthrough, this feature allows services running on Kubernetes, which already present a TLS encrypted endpoint, to multiplex incoming connections via a single external IP, their ingress controller's port 443.

Thank you to @glerchundi who drive this feature to completion.

Here is an example from the IngressRoute document showing the TCP passthrough in action:

apiVersion: contour.heptio.com/v1beta1
kind: IngressRoute
metadata:
  name: example
  namespace: default
spec:
  virtualhost:
    fqdn: tcp-passthrough.example.com
    tls:
      passthrough: true
  tcpproxy:
    services:
    - name: tcpservice
      port: 8080
  routes:
  - match: /
    services:
    - name: dummy
      port: 80

Please consult the IngressRoute documentation for more information.

Improvements to this feature we continue in future Contour releases.

Other improvements

• Statistics are now reported with a stable name that is not restricted to the 60 character cluster name. Fixes #689. Thanks @pims
• Documentation improvements and fixes. Thanks @samuela, @joshrosso, and @aknuds1
• Contour now records the service port in its status message if the service is found but lacks a matching port. Fixes #858
• Upgrade to Go 1.11.5, including the fix for CVE-2019-6486

Bug fixes

• A feedback loop where Contour would reprocess IngressRoute documents when their status was updated has been fixed. This issue affects all version of Contour where IngressRoute is supported. All Contour IngressRoute users should upgrade to version 0.9 or later. Thanks to @dbason for reporting the issue. See #854 for more information.
• The FQDN validation regex has been relaxed to include numbers in TLDs. Fixes #821. Thanks @PeteE

Upgrading

• Contour 0.9 requires Envoy 1.8.0.

   docker.io/envoyproxy/envoy-alpine:v1.8.0
  

  Previous versions of Envoy are not compatible with the configuration generated by Contour 0.9. Versions of Envoy later than 1.8.0 are not tested and not guaranteed to work with Contour 0.9.

Contour v0.8.1

Heptio is proud to present version 0.8.1 of Contour, our Envoy powered Kubernetes Ingress Controller.

Contour 0.8.1 is a bug fix release for the recently released 0.8.0

New and improved

• When using TCP forwarding IngressRoute a dummy spec.routes entry is no longer required to pass validation.
• Contour's holdoff notifier no longer spams stdout with messages about "delaying updates". This significantly reduces log volume from contour processes and improves the signal to noise ratio of Contour's logs.

Bug fixes

• docs: the format of the --use-proxy-protocol documentation has been updated to match the formatting of other examples. Thanks @wadeholler
• docs: a typo in the ingressroute documentation has been fixed. Thanks @jonas

Contour v0.8.0

Heptio is proud to present version 0.8 of Contour, our Envoy powered Kubernetes Ingress Controller.

New and improved

Contour 0.8 includes early support for TCP proxying of TLS encrypted traffic. Currently, TCP sessions must be encrypted with TLS. This is necessary so that Envoy can use SNI to route the incoming request to the correct service.

Here is an example IngressRoute document showing the TCP proxying in action:

apiVersion: contour.heptio.com/v1beta1
kind: IngressRoute
metadata:
  name: example
  namespace: default
spec:
  virtualhost:
    fqdn: tcp.example.com
    tls:
      secretName: secret
  tcpproxy:
    services:
    - name: tcpservice
      port: 8080
    - name: otherservice
      port: 9999
      weight: 20
  routes:
  - match: /
    services:
    - name: kuard
      port: 80

Please consult the IngressRoute documentation for more information.

Improvements to this feature we continue throughout the 0.8 and 0.9 series.

Bug fixes

• The missing Service definition for the deployment/ds-host-net example has been re-added.

Contour v0.7.0

Heptio is proud to present version 0.7 of Contour, our Envoy powered Kubernetes Ingress Controller.

New and improved

• Support for rewriting a request prefix has been added to IngressRoute. See https://github.com/heptio/contour/blob/master/docs/ingressroute.md#prefix-rewrite-support for more information. Thanks @stevesloka
• Support for contour.heptio.com/ingress.class has been added to IngressRoute. If the contour.heptio.com/ingress.class: production annotation is present on an IngressRoute object it will only be processed by Contour containers running with the flag --ingress-class-name=production. Thanks @amoskyler. Fixes #720
• All incoming HTTP requests are now timestamped by Envoy with an X-Request-Start : header. This header is understood by New Relic and datadog to time the end-to-end latency of a request. Thanks @yob. Fixes #646
• Support for TLS/1.3 is now enabled for all incoming requests. Thanks @chromefire. Fixes #672
• Gzip compression has been enabled for all responses. Thanks @yob. Fixes #310.
• Envoy has been upgraded to 1.7.0. Older version of Envoy are not compatible with Contour 0.7.0. Please see the Upgrading section for more information.
• Support for HTTP/1.0 requests has been added. Fixes #537
• Envoy now exposes a /healthz endpoint on port 8002 for use with the kubelet's readiness probe. Thanks @stevesloka. Fixes #695

Bugs fixed (since 0.6.1)

• k8s.io/client-go has been upgraded to v8.0.0 (Kubernetes v1.11.3).
• envoyproxy/go-control-plane has been upgraded to v0.6.0.
• AWS NLB documentation and example deployments have been updated for the service.beta.kubernetes.io/aws-load-balancer-type: nlb anotation added in Kubernetes 1.9.
• A bug affecting deployments which explicitly set the contour bootstrap --stats-address flag has been fixed. Thanks @josebiro. Fixes #742

Upgrade instructions

Due to a change in the xDS wire format Contour 0.7.0 requires Envoy 1.7.0. Earlier versions of Envoy will not work with Contour 0.7.0. Please ensure you upgrade your Deployments or Daemonsets to use this Envoy image

docker.io/envoyproxy/envoy-alpine:v1.7.0

If desired you can upgrade your Envoy container first, then your Contour container. This will cause Envoy to emit warnings like these

[2018-10-25 23:15:43.382][1][warning][misc] source/common/config/utility.cc:94] Setting a cluster name for API config source type envoy::api::v2::core::ConfigSource::GRPC is deprecated

When running against Contour 0.6.1. These warnings will cease once Contour is upgraded to 0.7.0.

Contour v0.6.1

Contour 0.6.1 is a bug fix release for Contour 0.6.0 users. It is recommended that all Contour users upgrade to 0.6.1.

Bugs fixed

• Update dns policy to match recommendation for pods are running with hostNetwork: true. Fixes #686. Thanks @stevesloka
• Fix websocket support. Envoy does not support websockets across multiple weighted backends, however Contour 0.6 always generated a weighted backend config even when only one backend was present (think of it as a weighting of 100%). This caused websocket requests to fail with a 503 error during processing. The fix is to only generate a weighted cluster configuration when there are more than one backends. This means for Contour 0.6.x websockets are only supported on routes with a single backend, see #732 for more information. Fixes #726. Thanks to @amoskyler for spotting the issue.

Contour v0.6.0

Contour 0.6.0

After several months hard work we are proud to bring you Contour 0.6.0.

New in this release

Here is a brief overview of the changes since Contour 0.5.0.

IngressRoute beta v1

The Ingress object was added to Kubernetes in version 1.1 to describe properties of a cluster-wide reverse HTTP proxy.
Since that time, the Ingress object has not progressed beyond the beta stage, and its stagnation inspired an explosion of annotations to express missing properties of HTTP routing.

The goal of the IngressRoute Custom Resource Definition (CRD) is to expand upon the functionality of the Ingress API to allow for a richer user experience as well as solve shortcomings in the original design.

Key IngressRoute Benefits

• Safely supports multi-team Kubernetes clusters, with the ability to limit which Namespaces may configure virtual hosts and TLS credentials.
• Enables delegation of routing configuration for a path or domain to another Namespace.
• Accepts multiple services within a single route and load balances traffic across them.
• Natively allows defining service weighting and load balancing strategy without annotations.
• Validation of IngressRoute objects at creation time and status reporting for post-creation validity.

See docs/ingressroute.md for more details.

Huge thanks to @stevesloka and @alexbrand who lead this work.

Rewritten Kubernetes to Envoy translator

Contour 0.6 features a completely rewritten Kubernetes to Envoy translation layer.
The translation layer was rewritten to support the new Ingressroute object alongside the current Ingress object.
The new translation layer works by constructing an in memory graph of the relationships between various Kubernetes API objects then uses this graph to produce the various xDS data sets required for Envoy.
In doing so a number of long standing issues where Clusters were duplicated or Services present in the Envoy configuration without matching routes have been resolved.

Additionally the new translator adds a short delay between sending updates to Envoy.
This delay allows multiple Kubernetes events to be coalesced into a single Envoy update which, while reducing the overhead of high update rates, should also avoid presenting temporarily incomplete configurations to Envoy.
The hold-off delay is currently no greater than 200ms after each update.
If updates have been continually delayed, say by a constant stream of messages, Envoy will receive an update from Contour at least once per second.

Websocket support

A new annotation, contour.heptio.com/websocket-routes allows Ingress authors to denote which paths in their Ingress object should be treated as Websocket enabled.
For example, this Ingress fragment:

apiVersion: extensions/v1beta1
kind: Ingress
metadata:
  annotations:
    contour.heptio.com/websocket-routes: "/ws1,/ws2"
spec:
  rules:
  - host: example.com
    http:
      paths:
      - path: /
        backend:
          serviceName: www
          servicePort: 8080
      - path: /ws1
        backend: 
          serviceName: websocket
          servicePort: 8080
      - path: /ws2
        backend:
          serviceName: www
          servicePort: 8080

Indicates that the Services referenced by paths /ws1 and /ws2 should be treated according to the Websocket protocol.
Thanks @glerchundi.

xDS filers are now supported

The xDS protocol supports watching only a specific set of resources.
This is now supported in Contour 0.6 and significantly reduces the amount of data transmitted between Contour and Envoy in response to changes in the Kubernetes API.

In addition, contour cli now supports an additional fourth parameter to allow the caller to watch a subset of resources.

Fixes #316

TLS minimum protocol version annotation

Contour supports a new Service annotation, contour.heptio.com/tls-minimum-protocol-version which is used to raise the minimum TLS version that will be used to communicate between Envoy and the Kubernetes Service.
By default, TLS version 1.1 will be used.

Thanks to @zxvdr.

Minor improvements

• Contour now uses client-go 1.10.
• Contour exposes a /debug/pprof endpoint for use with go tool pprof. See the troubleshooting documentation for more information.
• HTTP and HTTPS access logs can now be redirected to an arbitrary file. Thanks @zxvdr. Fixes #333.
• contour.heptio.com/upstream-protocol.h2c annotation is now supported.
• Contour now accepts HTTP/1.1 requests with Host: headers that contain a trailing :80 or :443 port number. Thanks to @mattalberts. Fixes #390.
• Contour now exports Prometheus metrics on port :8001.
• Documentation for deploying Contour on clusters that are not RBAC enabled has been removed.
• The Contour docker image has been rebased to Alpine 3.8.

Contour v0.5.0

Contour 0.5

Heptio is delighted to announce the release of Contour 0.5.

New and improved

The backend service protocol is now configurable

The Kubernetes Service object provides the ability to specify the layer 3 protocol, TCP or UDP, of a service but is mute on the subject of the service's layer 7 protocol. This presents a conundrum for those wishing to host services that speak HTTP/2 natively with as Envoy defaults to speaking HTTP/1 to all backend services.

To solve this Contour 0.5 introduces a new class of annotations on Service documents, contour.heptio.com/upstream-protocol.{protocol}, which specifies the protocol used by the upstream. The annotation value contains a list of port names and/or numbers separated by a comma that must match with the ones defined in the Service definition. For now, just h2 is supported, eg: contour.heptio.com/upstream-protocol.h2: "80,443" will specify that port's 80 and 443 defined in the Service spec speak HTTP/2.

Fixes #152 with warm thanks to @glerchundi.

gRPC rate limits between Contour and Envoy substantially increased

Contour 0.5.0 resolves two sources of insufficient gRPC rate limits between Contour and Envoy. The symptoms of hitting gRPC limits vary, but revolve around the theme of "Envoy doesn't see changes in the API server until I restart Contour".

The underlying cause is a large number of Service objects in your cluster -- these don't have to be associated with an Ingress. Currently Contour creates a CDS Cluster record for any Service object it learns about through the API (see #298). Each CDS record will cause Envoy to open a new EDS stream, one per Cluster, which can blow through the default limits that Envoy, as the gRPC client, and Contour, as the gRPC server, have set.

The easiest ways to detect if this issue is occurring in your cluster is to look for lines about "cluster warming"

[2018-04-03 03:34:16.920][1][info][upstream] source/common/upstream/cluster_manager_impl.cc:388] add/update cluster test2/reverent-noether/80 starting warming
[2018-04-03 03:34:16.922][1][info][upstream] source/common/upstream/cluster_manager_impl.cc:388] add/update cluster test2/serene-bohr/80 starting warming
[2018-04-03 03:34:16.924][1][info][upstream] source/common/upstream/cluster_manager_impl.cc:388] add/update cluster test2/sleepy-hugle/80 starting warming

Without a matching "warming complete" message.

Many thanks to Alexander Lukyanchenko (@Lookyan) who provided the patches to increase the gRPC limits on both the Contour and Envoy sides. Fixes #291, #293, #299, and #306.

This fix is also available in Contour 0.4.1.

Other bug fixes and improvements in this release

• Contour is now built with Go 1.10.1. Thanks @emman27
• Envoy has been upgraded to version 1.6.0. Thanks @shaneog
• All the deployment manifests now use the same set of command line flags. Thanks @cmaloney
• Preparatory work to address #272 and #227 has landed in this release. The remaining work on these issues will land in 0.6 and may be backported to 0.5.1 if necessary.

Upgrading

Contour now targets the Envoy 1.6.0 API. You should ensure that your Deployment or Daemonset manifests are pinned to Envoy's v1.6.0 tag.

spec:
  containers:
  - image: docker.io/envoyproxy/envoy-alpine:v1.6.0

Contour v0.4.1

Contour 0.4.1 is a bug fix release for Contour 0.4.0.

This release contains a small number of bug fixes. All Contour 0.4.0 users should upgrade to 0.4.1.

Bug fixes and improvements (relative to Contour 0.4.0)

Contour 0.4.1 resolves two sources of insufficient gRPC rate limits between Contour and Envoy. The symptoms of hitting gRPC limits vary, but revolve around the theme of "Envoy doesn't see changes in the API server until I restart Contour".

The underlying cause is a large number of Service objects in your cluster -- these don't have to be associated with an Ingress. Currently Contour creates a CDS Cluster record for any Service object it learns about through the API (see #298). Each CDS record will cause Envoy to open a new EDS stream, one per Cluster, which can blow through the default limits that Envoy, as the gRPC client, and Contour, as the gRPC server, have set.

The easiest ways to detect if this issue is occurring in your cluster is to look for lines about "cluster warming"

[2018-04-03 03:34:16.920][1][info][upstream] source/common/upstream/cluster_manager_impl.cc:388] add/update cluster test2/reverent-noether/80 starting warming
[2018-04-03 03:34:16.922][1][info][upstream] source/common/upstream/cluster_manager_impl.cc:388] add/update cluster test2/serene-bohr/80 starting warming
[2018-04-03 03:34:16.924][1][info][upstream] source/common/upstream/cluster_manager_impl.cc:388] add/update cluster test2/sleepy-hugle/80 starting warming

Without a matching "warming complete" message.

Many thanks to Alexander Lukyanchenko (@Lookyan) who provided the patches to increase the gRPC limits on both the Contour and Envoy sides. Fixes #291, #293, #299, and #306.

Upgrading

Contour 0.4.1 incorporates a changes to the sample deployment/ manifests to pin the version of Envoy to the v1.6.0 image tag. The Envoy 1.6.0 release occurred after 0.4.0 so the Contour 0.4.0 manifests shipped with a hash.

All Contour users should upgrade to the v1.6.0 image tag as this change is already present in master and will be included in Contour 0.5.0 shipping in a few weeks. Fixes #280. Thanks @shaneog

Contour v0.4.0

Contour 0.4

Heptio is pleased to announce the release of Contour 0.4.

I'd like to extend a warm thanks to all of the contributors, you're awesome.

New and improved

In Contour 0.4 the JSON v1 bootstrap configuration option is removed. The corresponding v1 JSON API is also removed from the Contour codebase. Consult the upgrade notes for how to update your Deployment or Daemonset manifests to the YAML bootstrap configuration format.

Many general improvements made to the Contour → Envoy transmission path

Much effort has been expended on the Contour to Envoy gRPC API, including a set of end to end tests to improve the robustness of configurations that are transfered to Envoy.

Additional annotations

Contour now supports the following annotations to control Envoy's retry behaviour:

• contour.heptio.com/request-timeout to control the amount of time Envoy will wait for a backend to respond.
• contour.heptio.com/retry-on to control under which conditions Envoy should retry a request.
• contour.heptio.com/num-retries to control the number of retries Envoy will perform.
• contour.heptio.com/per-try-timeout to control the request timeout per attempt.
  For more information please consult the annotation documentation. Thanks @cmaloney. Fixes #164 and #221.

Ingress class now configurable

By default Contour responds to the ingress class annotation kubernetes.io/ingress.class: contour where present. However, if required while migrating from another ingress controller, you can pass the flag --ingress-class-name to adjust the ingress.class name that Contour will respond to. Thanks @nikkau. Fixes #255.

TLS 1.1 is now mandatory

Following the advice of the PCI Security Standards Council Contour 0.4 will configure Envoy to require TLS 1.1 or later. Thanks @sevein. Fixes #185.

Certificate information is now sent in-line in the gRPC message

Due to a limitation in Envoy Contour 0.3 exchanged certificate data with Envoy via a shared file system.
This limitation has been addressed and Contour 0.4 transmits certificate data directly to Envoy in gRPC API response messages. Thanks @sevein. Fixes #158.

Contour and Envoy can now live in separate pods

Although not currently utilised, Contour and Envoy can now exist in separate pods. This is accomplished by the --xds-address and --xds-port flags passed to both contour bootstrap and contour serve which can be used to deploy Contour as a ReplicaSet which Envoy is a Daemonset. Thanks to @sevein. Fixes #165

ingress.kubernetes.io/force-ssl-redirect: "true" annotation now applies on a per Ingress basis

In Contour version 0.3 and earlier, if any Ingress for a virtual host specified the ingress.kubernetes.io/force-ssl-redirect: "true" annotation, then all routes for the virtual host were redirected with a 301.

In Contour 0.4 this behaviour is applied per Ingress, that is, to all routes in an Ingress object. This allows a split Ingress setup in which some routes on a virtual host are redirected with a 301, and others are not. Fixes #250.

Tutorial for Prometheus metrics

A tutorial for configuring Prometheus to scrape Envoy metrics was added. Envoy provides very rich metrics, for example you can get requests grouped by service and status code or the amount of retries and timeout for a given service.

Other bug fixes and improvements in this release

• The Contour Docker image no longer bundles the ocid and gcp authentication plugins, because they are not required for --incluster deployments.
• Daemonset or Deployment examples now specify the --v2-config-only flag to instruct Envoy to not fall back to parsing an invalid configuration file as the deprecated v1 JSON format. This should aid debugging contour bootstrap issues. Thanks @cmaloney
• Updated to the latest envoyproxy/go-control-plane library. Thanks @vaamarnath. Fixes #225
• Contour has switched to sirupsen/logrus as its logging library. Fixes #162.
• Our troubleshooting documentation now includes a simple way to access Envoy's Admin interface which is useful for examining the state of its route and cluster tables.
• Issues related to updating Service and Ingress objects in place with kubectl edit are fixed with a new caching layer in the translator package.

Upgrading

Until Envoy 1.6 is released it is recommended to pin the version of Envoy used in your deployments to a known hash. The recommended hash is

spec:
  containers:
  - image: docker.io/envoyproxy/envoy-alpine:e6ff690611b8a3373f6d66066b52d613873e446e

Consult the upgrade notes for how to update your Deployment or Daemonset manifests to the YAML bootstrap configuration format.