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.

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

Contour 0.3.1 is a bug fix release for Contour 0.3.

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

Bug fixes and improvements (compared to Contour 0.3.0)

• oidc and gcp auth plugins are no longer built into the gcr.io/heptio/contour docker image. This makes the image slightly smaller.
• Contour now negotiates HTTP/2 over HTTPS connections. Thanks @cmaloney. Fixes #168
• Several fixes to the deployment/ manifests make them compatible with Kubernetes 1.8 and improve the debugging experience. Thanks @cmaloney. Fixes #138
• Services with long names or namespaces (combined exceed 60 characters) are now correctly handled. Thanks @alexbrand. Fixes #186

Heptio is pleased to announce the release of Contour 0.3.

New and improved

The headline features of this release are:

TLS support

Contour now supports HTTP and HTTPS ingress. Contour TLS support works with the standard ingress object. You can read more about Contour's TLS support here.

More supported annotations

Support is added for the following annotations on the service and ingress objects:

• kubernetes.io/ingress.allow-http: "false" removes the ingress configration from the non TLS listener. Envoy does not serve traffic for your ingress's vhost on port 80.
• ingress.kubernetes.io/force-ssl-redirect: "true" causes Envoy to issue an unconditional 301 redirect to the HTTPS version of your site.

gRPC API is now GA

Support for Envoy's version 2 gRPC based API, introduced in Contour 0.2, is now marked GA. The REST API does not support new Envoy features such as SNI. Support for the REST API is deprecated and will be removed in Contour 0.4.

Other improvements in this release

• Contour no longer sends updates to Envoy periodically. Changes in the Kubernetes API are streamed to Envoy as they occur. In a steady state, no traffic flows from Contour to Envoy.
• The address and port for Envoy's HTTP and HTTPS listeners are now configurable. This will be useful for anyone using a Daemonset with host networking. This can also be used to force Envoy to bind to IPv6.
• Contour now supports the PROXY protocol to recover the remote IP of connections via an ELB in TCP mode. To enable this, add the --use-proxy-protocol flag to the flags for your contour Deployment or Daemonset.
• Update to client-go release 6.

Bug fixes (compared to Contour 0.2.1)

• The glog library is now properly initalised on contour serve startup. Fixes #113. Thanks @willmadison

Upgrading

Contour 0.3 makes the YAML v2 bootstrap configuration format the default. In Contour 0.4 the JSON v1 bootstrap configuration option will be removed. Consult the upgrade notes for how to update your Deployment or Daemonset manifests to the YAML bootstrap configuration format.

Contour 0.2.1 is a bug fix release for the gRPC support added in Contour 0.2.

This release contains a single change to the schema of v2 bootstrap configuration and gRPC LDS response messages to match a recent change in Envoy.

If you are not using the v2 configuration mode or gRPC you do not need to upgrade.

Bugs fixed

• Contour generates an out of date configuration in v2 configuration mode. Fixes #136

Heptio is pleased to announce the release of Contour 0.2.0.

New and Improved

Contour 0.2.0 features support for Envoy's gRPC management server API.

gRPC API support

Contour 0.2.0 adds beta support for Envoy's gRPC based managment server API.
The gRPC API enables streaming of configuration information from Contour to Envoy, removing the need for polling, and reducing the latency between a configuration changes in the Kubernetes API server and the change becoming visible to Envoy.

gRPC support is evolving rapidly and is expected to become the default management server protocol in the 0.3 to 0.4 timeframe.

Upgrading

For Contour 0.2.0 the original REST API remains the default, however if you wish to experiment with gRPC a [sample deployment][2] is provided.
The key change is the name of the configuration file generated during pod initalization.
Specifically, the switch from

contour bootstrap /config/config.json

To

contour bootstrap /config/config.yaml

In your deployment or daemonset's initContainer stanza with a matching update to the -c flag passed to the envoy container will switch from REST to gRPC.

For further details, consult the deployment-grpc-v2 example.

Bug fixes

• Contour now truncates long cluster names to Envoy's default limit of 60 characters. Fixes #25
• Quickstart links are now provided over https. Fixes #23

Introducing Contour

Contour is an Ingress controller for Kubernetes that works by deploying the Envoy proxy as a reverse proxy and load balancer. Unlike other Ingress controllers, Contour supports dynamic configuration updates out of the box while maintaining a lightweight profile.

This is an early release so that we can start sharing with the community. Check out the roadmap to see where we plan to go with the project.

And see the launch blog post for our vision of how Contour fits into the larger Kubernetes ecosystem.