Contour v0.12.0

VMware is proud to present version 0.12 of Contour, our Envoy powered Kubernetes Ingress Controller. Again, without the help of the many community contributors, this wouldn't have been possible. Thank you!

New and improved

Contour 0.12 includes several new features as well as the usual smattering of fixes and minor improvements.

Support for per route backend timeouts and retries

Support for specifying backend timeouts and retries has been added to ingressroute. These are enabled via the timeoutPolicy and retryPolicy keys, respectively. eg.

apiVersion: contour.heptio.com/v1beta1
kind: IngressRoute
metadata:
  name: request-timeout
  namespace: default
spec:
  virtualhost:
    fqdn: timeout.bar.com
  routes:
  - match: /
    timeoutPolicy:
      request: 1s
    retryPolicy:
      count: 3
      perTryTimeout: 150ms
    services:
    - name: s1
      port: 80

If timeoutPolicy is present then the backend service must complete processing the request in the duration specified. If timeoutPolicy is present without a request key, the timeout is inferred to be infinite. If no timeoutPolicy is present, Envoy will use its default timeout, which is currently 15s.

If retryPolicy is present and perTryTimeout is set a requests to backends will be retried after the duration specified up to the total request duration specified in timeoutPolicy (if present). By default the number of retries is 1, but can be increased with the count key.

See the design document and ingressroute for more information

Thanks to @rohandvora, @prasoontelang and @stevesloka.

Verification of TLS enabled backends

Contour 0.11 added support for enabling TLS communication between Envoy and backend services. Contour 0.12 adds the ability to verify that the backend pod Envoy communicates with is who it says it is. This is achieved in three steps.

1. The backend Service must use TLS to communicate with Envoy. This is achieved with the contour.heptio.com/upstream-protocol.tls annotation on the Service document.
2. The certificate authority used to issue the TLS certificate the backend service offers should be placed in a Secret in the same namespace as the IngressRoute and the Service. eg.

% kubectl create secret generic my-certificate-authority --from-file=./ca.key

3. An validation key is created for each service in the matching route

apiVersion: contour.heptio.com/v1beta1
kind: IngressRoute
metadata:
  name: secure-backend
spec:
  virtualhost:
    fqdn: www.example.com
  routes:
    - match: /
      services:
        - name: service
          port: 8443
          validation:
            caSecret: my-certificate-authority
            subjectName: backend.example.com

Both the caSecret and subjectName keys are required.

See the design document and the ingressroute documentation for more information.

Thanks again to @stevesloka

SDS xDS API

While not directly user facing Contour 0.12 adds support for Envoy's Secret Discovery Service (SDS) API.

In the future SDS support will aide in reducing the number of configuration changes sent from Contour to Envoy, and will enable secure communication between Contour and Envoy.

Thanks to @vaamarnath and Matt Alberts. Fixes #898.

AES128-* and AES256-* removed permitted ciphers list

Contour no longer offers ciphers matching AES128-* or AES256-* as they are considered to be weak. This improves the SSL Lab's score for hosts secured by Contour.

See #1011 for more details

Thanks @yob

Sample grafana dashboard

The Contour distribution now includes a set of predefined Grafana dashboards. See deployment/grafana and deployment/prometheus for more information.

Thanks @stevesloka, @alexbrand and @rata.

Other improvements

• regenerate CRDs. Thanks @unicell. Fixes #993.
• force glog to write to stderr. Thanks @unicell. Updates #959
• copy edit documentation. Thanks @lostllama.
• fix issues regenerating CRDs after the switch to go modules. Thanks @glerchundi. Fixes #996
• Contour now reports how many pending changes have been queued by the holdoff notifier. Thanks Matt Alberts.

Upgrading

• Contour 0.12 requires Envoy 1.9.1.

  docker.io/envoyproxy/envoy:v1.9.1
  

  Previous versions of Envoy are not compatible with the configuration generated by Contour 0.11. If Envoy fails to start after upgrading Contour to 0.12 with an error similar to this, you have not upgraded Envoy to 1.9.1.

  [2019-04-08 01:54:58.396][000001][critical][main] [source/server/server.cc:86] error initializing configuration '/config/contour.json': Unable to parse JSON as proto (INVALID_ARGUMENT:normalize_path: Cannot find field.): {"codec_type":"AUTO","http_filters":[{"name":"envoy.health_check","config":{"headers":[{"name":":path","exact_match":"/healthz"}],"pass_through_mode":"false"}},{"name":"envoy.router"}],"stat_prefix":"stats","normalize_path":true,"route_config":{"virtual_hosts":{"routes":[{"match":{"prefix":"/stats"},"route":{"cluster":"service_stats"}}],"domains":["*"],"name":"backend"}}}                                [2019-04-08 01:54:58.397][000001][info][main] [source/server/server.cc:507] exiting
  

  Versions of Envoy later than 1.9.1 are not tested and not guaranteed to work with Contour 0.12.0.

Contour v0.11.0

VMware is proud to present version 0.11 of Contour, our Envoy powered Kubernetes Ingress Controller. As always, thank you to the many community contributors -- we literally couldn't do it without you!

Contour 0.11 address a path traversal security issue in Envoy 1.9.0. It is recommended that all users upgrade to Contour 0.11 and the corresponding Envoy 1.9.1 release.

New and improved

Contour 0.11 includes several new features and one important security patch.

Envoy 1.9.1 and CVE-2019-9901 mitigations

Envoy 1.9.0 and earlier are vulnerable to a path normalisation attack. For example, a remote attacker may craft a path with a relative path, e.g. /public/../admin, to bypass access control, e.g. a block on /admin. When deployed with Contour as an ingress controller this means traffic which was intended to be directed via one route may be sent to another via a denormalised request path.

The fix for this attack is available in Envoy 1.9.1, however it is not sufficient to simply upgrade Envoy as path normalisation is currently opt in. Contour 0.11.0 generates the correct configuration to secure Envoy 1.9.1 by requesting path normalisation for all routes.

Details of the vulnerability

Fixes #983. Thanks @stevesloka

Support of TLS enabled backends

Contour 0.11 adds the ability to connect to backend Service that require TLS. This is enabled by a new annotation on the Service object:

contour.heptio.com/upstream-protocol.tls: {port,portName}

The question of what L7 protocol a Service's port speaks is a property of the Service, not the Ingress/IngressRoute, hence the annotation is placed on the Service object.

See the Annotation documentation for more information

Note: Envoy does not perform any validation of the certificate presented by the backend Service.

Fixes #406, #569, and #963.

Thanks again to @stevesloka

Other improvements

• A design document for adding retry and timeout behaviour to IngressRoute has been merged. Big thank you to @prasoontelang. Updates #815.
• Contour is now built with Go 1.12.1 (1.12.2 was not available at the time of this release). Thanks @avni. Fixes #848
• Upgrade to envoyproxy/go-control-plane v0.6.9. Fixes #933
• Upgrade to k8s.io/client-go v1.12.6. Thanks @vaamarnath. Fixes #934.
• Improve PR contribution templates. Thanks @andrewsykim.
• Contour now uses the shared informer client-go infrastructure. Thanks @andrewsykim.
• Contour has migrated from dep to Go modules for dependency management. Thanks @vaamarnath. Fixes #598.
• Envoy's deprecated --v2-config-only flag has been removed from our sample deployments/. Thanks @rata. Fixes #971.
• Prometheus integration documentation has been updated. Thanks @indradhanush.

Bug fixes

Several bugs in CRD validation have been fixed during the 0.11 development cycle.

• The documentation and validation for TLS Certificate validation (introduced in Contour 0.10) incorrectly suggested that spec.delegations took only a single item. This is incorrect, spec.delegations takes a list. The documentation has been corrected and additional CRD validation introduced to reject the previously incorrect YAML. Thanks to @joshrosso for spotting the issue. Fixes #977.
• A bug in the validation for the Ingressroute spec.tls.secretName prevented names with a forward slash, /, from being used. This has been corrected. Thanks @arminbuerkle. Fixes #965.
• The deployment/ds-hostnet-split example YAML failed to pass validation under newer versions of Kubernetes. This has been fixed. Thanks @stevesloka. Fixes #940.
• A typo in the contour serve documentation has been fixed. Thanks @shivanshu21. Fixes #966.

Upgrading

• Several issues with CRD validation have been fixed in Contour 0.11. Please redeploy Contour using the supplied deployment/ artifacts.
• Envoy's --v2-config-only flag has been deprecated in Envoy 1.9.x, and will be removed entirely in Envoy 1.10. Please remove it from your deployments to prevent Envoy failing to start.
• Contour 0.11 requires Envoy 1.9.1.

  docker.io/envoyproxy/envoy:v1.9.1
  

  Previous versions of Envoy are not compatible with the configuration generated by Contour 0.11. If Envoy fails to start after upgrading Contour to 0.11 with an error similar to this, you have not upgraded Envoy to 1.9.1.

  [2019-04-08 01:54:58.396][000001][critical][main] [source/server/server.cc:86] error initializing configuration '/config/contour.json': Unable to parse JSON as proto (INVALID_ARGUMENT:normalize_path: Cannot find field.): {"codec_type":"AUTO","http_filters":[{"name":"envoy.health_check","config":{"headers":[{"name":":path","exact_match":"/healthz"}],"pass_through_mode":"false"}},{"name":"envoy.router"}],"stat_prefix":"stats","normalize_path":true,"route_config":{"virtual_hosts":{"routes":[{"match":{"prefix":"/stats"},"route":{"cluster":"service_stats"}}],"domains":["*"],"name":"backend"}}}                                [2019-04-08 01:54:58.397][000001][info][main] [source/server/server.cc:507] exiting
  

  Versions of Envoy later than 1.9.1 are not tested and not guaranteed to work with Contour 0.11.

Contour v0.10.0

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

New and improved

Contour 0.10 features several new features.

Wildcard support via TLS Certificate Delegation

The headline feature for Contour 0.10 is something we call TLS Certificate Delegation. The primary usevcase for TLS Certificate Delegation is enabling an administrator, the owner of a k8s Secret containing a wildcard style--*.mycorp.com--style TLS certificate, to delegate the permission to reference that certificate by name to another namespace.

In this way, administrators do not need to copy tasty wildcard certificates to each namespaces that wants to use them, instead an Ingress or IngressRoute owner can reference the wildcard certificate by name, assuming the administrator has created the appropriate delegation object.

Certificate delegation is opt in. To find out more about this feature, please refer to the following documents;

• TLS Certificate delegation design document
• IngressRoute documentation

Fixes #410

Configurable secure and insecure external ports

Due to a long standing limitation in Envoy, if Contour is not configured to present Envoy at your cluster's edge on ports other than the traditional 80 and 443, Envoy will reject the traffic because some user agents include that foreign port in the Host: header.

To address this two new flags have been added to contour serve, --envoy-external-http-port and --envoy-external-https-port. These default to 80 and 443 respectively.

If you have deployed Contour at your edge using non standard port numbers, you should set these two flags to ensure Envoy can correctly route traffic that arrives with trailing port numbers in the Host: header.

Please see the Upgrading section for information for upgrading from previous incarnations of these flags.

Fixes #610

Other improvements

• Contour now supports the PROXY v1 and v2 preamble headers. The former is predominantly used by AWS ELB instances, the latter is used by HA Proxy. Fixes #802
• Upgrade to envoyproxy/go-control-plane v0.6.4.
• Upgrade to k8s.io/client-go v1.11.7.
• Documentation improvements. Thanks @ramnes.
• Addional tests for the contour serve --access-log flag. Fixes #475. Thanks @vaamarnath.

Bug fixes

• Envoy now stops sending traffic to an endpoint that has active health checking enabled. Previously if the endpoint was removed from the cluster, Envoy would continue to send traffic until the health check timeouts fired. Fixes #603. Thanks @stevesloka and @alexbrand.

Upgrading

• The bootstrap configuration file format has changed from YAML to JSON. This change should be invisible to all users. If not, please redeploy Contour using the supplied deployment/ artifacts.

• The --envoy-http-port and --envoy-https-port flags have been renamed to --envoy-service-http-port and --envoy-service-https-port respectively. The values of these flags default to 8080 and 8443 respectively and should match the ports in the heptio-contour/contour Service document.

• Contour 0.10 requires Envoy 1.9.0.

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

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

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.