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.

Contour v0.3.1

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

Contour v0.3.0

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

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

Contour v0.2.0

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

Contour v0.1.0

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.