Resources on Contour

Compatibility Matrix

Mon, 01 Jan 0001 00:00:00 +0000

This page documents the compatibility matrix of versions of Contour, Envoy, Kubernetes, and Gateway API. These combinations of versions are specifically tested in CI and supported by the Contour maintainers.

Compatibility Matrix

Contour Version	Envoy Version	Kubernetes Versions	Gateway API Version
main	1.35.8	1.34, 1.33, 1.32	1.3.0
1.33.1	1.35.8	1.34, 1.33, 1.32	1.3.0
1.33.0	1.35.2	1.34, 1.33, 1.32	1.3.0
1.32.2	1.34.12	1.33, 1.32, 1.31	1.2.1
1.32.1	1.34.4	1.33, 1.32, 1.31	1.2.1
1.32.0	1.34.1	1.33, 1.32, 1.31	1.2.1
1.31.3	1.34.12	1.32, 1.31, 1.30	1.2.1
1.31.2	1.34.4	1.32, 1.31, 1.30	1.2.1
1.31.1	1.34.1	1.32, 1.31, 1.30	1.2.1
1.31.0	1.34.0	1.32, 1.31, 1.30	1.2.1
1.30.5	1.31.10	1.30, 1.29, 1.28	1.1.0
1.30.4	1.31.8	1.30, 1.29, 1.28	1.1.0
1.30.3	1.31.6	1.30, 1.29, 1.28	1.1.0
1.30.2	1.31.5	1.30, 1.29, 1.28	1.1.0
1.30.1	1.31.3	1.30, 1.29, 1.28	1.1.0
1.30.0	1.31.0	1.30, 1.29, 1.28	1.1.0
1.29.5	1.30.10	1.29, 1.28, 1.27	1.0.0
1.29.4	1.30.9	1.29, 1.28, 1.27	1.0.0
1.29.3	1.30.7	1.29, 1.28, 1.27	1.0.0
1.29.2	1.30.4	1.29, 1.28, 1.27	1.0.0
1.29.1	1.30.2	1.29, 1.28, 1.27	1.0.0
1.29.0	1.30.1	1.29, 1.28, 1.27	1.0.0
1.28.8	1.29.12	1.29, 1.28, 1.27	1.0.0
1.28.7	1.29.10	1.29, 1.28, 1.27	1.0.0
1.28.6	1.29.7	1.29, 1.28, 1.27	1.0.0
1.28.5	1.29.5	1.29, 1.28, 1.27	1.0.0
1.28.4	1.29.4	1.29, 1.28, 1.27	1.0.0
1.28.3	1.29.3	1.29, 1.28, 1.27	1.0.0
1.28.2	1.29.2	1.29, 1.28, 1.27	1.0.0
1.28.1	1.29.1	1.29, 1.28, 1.27	1.0.0
1.28.0	1.29.1	1.29, 1.28, 1.27	1.0.0
1.27.4	1.28.4	1.28, 1.27, 1.26	0.8.1
1.27.3	1.28.3	1.28, 1.27, 1.26	0.8.1
1.27.2	1.28.2	1.28, 1.27, 1.26	0.8.1
1.27.1	1.28.1	1.28, 1.27, 1.26	0.8.1
1.27.0	1.28.0	1.28, 1.27, 1.26	0.8.1
1.26.3	1.27.4	1.28, 1.27, 1.26	0.8.1
1.26.2	1.27.3	1.28, 1.27, 1.26	0.8.1
1.26.1	1.27.2	1.28, 1.27, 1.26	0.8.1
1.26.0	1.27.0	1.28, 1.27, 1.26	0.8.0
1.25.3	1.26.6	1.27, 1.26, 1.25	0.6.2
1.25.2	1.26.4	1.27, 1.26, 1.25	0.6.2
1.25.1	1.26.4	1.27, 1.26, 1.25	0.6.2
1.25.0	1.26.1	1.27, 1.26, 1.25	0.6.2
1.24.6	1.25.11	1.26, 1.25, 1.24	0.6.0
1.24.5	1.25.9	1.26, 1.25, 1.24	0.6.0
1.24.4	1.25.6	1.26, 1.25, 1.24	0.6.0
1.24.3	1.25.4	1.26, 1.25, 1.24	0.6.0
1.24.2	1.25.2	1.26, 1.25, 1.24	0.6.0
1.24.1	1.25.1	1.26, 1.25, 1.24	0.6.0
1.24.0	1.25.0	1.26, 1.25, 1.24	0.6.0
1.23.6	1.24.10	1.25, 1.24, 1.23	0.5.1
1.23.5	1.24.5	1.25, 1.24, 1.23	0.5.1
1.23.4	1.24.3	1.25, 1.24, 1.23	0.5.1
1.23.3	1.24.2	1.25, 1.24, 1.23	0.5.1
1.23.2	1.24.1	1.25, 1.24, 1.23	0.5.1
1.23.1	1.24.1	1.25, 1.24, 1.23	0.5.1
1.23.0	1.24.0	1.25, 1.24, 1.23	0.5.1
1.22.6	1.23.7	1.24, 1.23, 1.22	0.5.0
1.22.5	1.23.5	1.24, 1.23, 1.22	0.5.0
1.22.4	1.23.4	1.24, 1.23, 1.22	0.5.0
1.22.3	1.23.3	1.24, 1.23, 1.22	0.5.0
1.22.2	1.23.3	1.24, 1.23, 1.22	0.5.0
1.22.1	1.23.1	1.24, 1.23, 1.22	0.5.0
1.22.0	1.23.0	1.24, 1.23, 1.22	0.5.0
1.21.3	1.22.6	1.23, 1.22, 1.21	0.4.3
1.21.2	1.22.6	1.23, 1.22, 1.21	0.4.3
1.21.1	1.22.2	1.23, 1.22, 1.21	0.4.3
1.21.0	1.22.0	1.23, 1.22, 1.21	0.4.3
1.20.2	1.21.3	1.23, 1.22, 1.21	0.4.1
1.20.1	1.21.1	1.23, 1.22, 1.21	0.4.1
1.20.0	1.21.0	1.23, 1.22, 1.21	0.4.1
1.19.1	1.19.1	1.22, 1.21, 1.20	0.3.0
1.19.0	1.19.1	1.22, 1.21, 1.20	0.3.0
1.18.3	1.19.1	1.21, 1.20, 1.19	0.3.0
1.18.2	1.19.1	1.21, 1.20, 1.19	0.3.0
1.18.1	1.19.1	1.21, 1.20, 1.19	0.3.0
1.18.0	1.19.0	1.21, 1.20, 1.19	0.3.0
1.17.2	1.18.4	1.21, 1.20, 1.19	0.3.0
1.17.1	1.18.3	1.21, 1.20, 1.19	0.3.0
1.17.0	1.18.3	1.21, 1.20, 1.19	0.3.0
1.16.1	1.18.4	1.21, 1.20, 1.19	0.3.0
1.16.0	1.18.3	1.21, 1.20, 1.19	0.3.0
1.15.2	1.18.4	1.21, 1.20, 1.19	0.3.0
1.15.1	1.18.3	1.21, 1.20, 1.19	0.3.0
1.15.0	1.18.2	1.21, 1.20, 1.19	0.3.0
1.14.2	1.17.4	1.20, 1.19, 1.18	0.2.0
1.14.1	1.17.2	1.20, 1.19, 1.18	0.2.0
1.14.0	1.17.1	1.20, 1.19, 1.18	0.2.0
1.13.1	1.17.1	1.20, 1.19, 1.18	0.2.0
1.13.0	1.17.0	1.20, 1.19, 1.18	0.2.0
1.12.0	1.17.0	1.19, 1.18, 1.17	N/A
1.11.0	1.16.2	1.19, 1.18, 1.17	N/A
1.10.1	1.16.2	1.19, 1.18, 1.17	N/A
1.10.0	1.16.0	1.19, 1.18, 1.17	N/A
1.9.0	1.15.1	1.18, 1.17, 1.16	N/A

Notes on Compatibility

As of Contour version 1.16.0, Contour only subscribes to Ingress v1 resources (and no longer falls back to Ingress v1beta1). The minimum compatible Kubernetes version for Contour 1.16.0 and above is Kubernetes 1.19.

Contour Adopters

Mon, 01 Jan 0001 00:00:00 +0000

If you’re using Contour and want to add your organization to this list, please submit a pull request!

Success Stories

Below is a list of adopters of Contour in production environments that have publicly shared the details of how they use it.

Migrating from Openshift Router to Contour in SnappCloud SnappCloud is the private cloud infrastructure provider for Snapp, the largest ride-hailing platform in the Middle East. In addition to ride-hailing, Snapp supports a range of services including online doctor consultations, food shopping, and more. Within our infrastructure, we utilize multiple OKD (OpenShift) clusters. We have successfully transitioned from the OpenShift Router Controller to Contour for our ingress needs. To maintain consistent behavior during this migration, we employed the route-to-contour-httpproxy project. This Kubernetes controller is designed for converting OpenShift HAProxy Route to Contour HTTPProxy, incorporating default values of OpenShift Router HAProxy and converting OpenShift-specific annotations to HTTPProxy configurations.

Contour Deprecation Policy

Mon, 01 Jan 0001 00:00:00 +0000

Contour publishes a few APIs, the most notable being the projectcontour.io api group of Kubernetes objects and their associated helper code, the command line for contour, and the Contour configuration file. Each of these have deprecation policies, with all of them being based on the Kubernetes API deprecation policy.

`projectcontour.io` API groups (aka Contour CRDs)

Our Kubernetes CRDs use the Kubernetes API deprecation conventions, including a similar deprecation timeline.

There are three levels of stability, Alpha, Beta and GA (in increasing order).
We may skip the Beta level when we are reasonably confident the schema is good.

We use similar rules as Kubernetes:

Contour Ecosystem

Mon, 01 Jan 0001 00:00:00 +0000

This is a list of Contour related resources. If you have a suggestion on what to add, please don’t hesitate to submit a pull request!

Plugins

Argo Rollouts: The Argo Rollouts plugin implementing the Contour HTTPProxy traffic control in progressive delivery scenarios.

Documents

Open Service Mesh: OSM takes a simple approach for users to uniformly manage, secure, and get out-of-the box observability features for highly dynamic microservice environments.
Linkerd: Linkerd is a service mesh for Kubernetes. It makes running services easier and safer by giving you runtime debugging, observability, reliability, and security—all without requiring any changes to your code.

Contour Philosophy

Mon, 01 Jan 0001 00:00:00 +0000

Contour is a Layer 7 HTTP middleware reverse proxy for enabling ingress to Kubernetes clusters.

Non Goals

Contour is not a service mesh, nor is it the intention for Contour to expose all of the features or configuration options of Envoy.

Contour is not intended for proxying layer 4 protocols such as TCP or UDP except insofar as they are needed to deliver HTTP. So, TCP proxying is available, but expects the proxying to be used for passing through HTTPS. In the future, some UDP support may be added so that we can support QUIC, which uses UDP as a transport. Using Contour to proxy raw TCP or UDP traffic may work, but is not the intended usage.

Contour Release Process

Mon, 01 Jan 0001 00:00:00 +0000

Minor release process
Patch release process
RC release process

Minor Release Process

Overview

A minor release is e.g. v1.11.0.

A minor release requires:

website updates
a release branch to be created
YAML to be customized
an update to dependabot config
a release tag to be created
a GitHub release with release notes
submitting a Gateway API conformance report (if applicable)
public communication
cleanup

Process

Set environment variables

Set environment variables for use in subsequent steps:

Contour Support Policy

Mon, 01 Jan 0001 00:00:00 +0000

This document describes which versions of Contour are supported by the Contour team.

Supported releases

Contour is changing both to quarterly releases and three supported releases.

The first Contour version covered by the quarterly release cadence is Contour v1.20, released in Jan 2022.

At the time it is released, it will be the only supported version, and versions 1.21 and 1.22 will continue supporting back to Contour 1.20.

When Contour 1.23 releases, Contour 1.20 will fall out of support.

Contour Tagging Policy

Mon, 01 Jan 0001 00:00:00 +0000

This document describes Contour’s image tagging policy.

Released versions

ghcr.io/projectcontour/contour:<SemVer>

Contour follows the Semantic Versioning standard for releases. Each tag in the github.com/projectcontour/contour repository has a matching image. eg. ghcr.io/projectcontour/contour:1.33

ghcr.io/projectcontour/contour:v<major>.<minor>

This tag will point to the latest available patch of the release train mentioned. That is, it’s :latest where you’re guaranteed to not have a minor version bump.

Latest

ghcr.io/projectcontour/contour:latest

The latest tag follows the most recent stable version of Contour.

Contour Threat Model and Security Posture

Mon, 01 Jan 0001 00:00:00 +0000

Contour is an ingress controller that works as an Envoy control plane, configuring the Envoy data plane, which actually carries traffic from outside to inside the cluster.

Reporting Security issues

For reporting security issues, please see the reporting process documentation.

Inputs

Contour’s inputs are:

configuration and command line flags set by its administrator
Kubernetes objects that represent the desired load balancer/data plane configuration.

Expected Users

The expected users of of Contour are:

Contributing Technical Documentation

Mon, 01 Jan 0001 00:00:00 +0000

Contour Technical Documentation Contributing Guide

The purpose of the Working Group is to build up a self-sustaining community around documentation for Contour. We have an initial need to rework the existing documentation based on the recommendations outlined in the CNCF Tech Docs Review, and a continuous need for documentation being added/edited/removed for releases going forward. This group is open to contributors of all levels, the only requirement is being interested in helping with docs!

Frequently Asked Questions

Mon, 01 Jan 0001 00:00:00 +0000

Q: What’s the relationship between Contour and Istio?

Both projects use Envoy under the covers as a “data plane”. They can both be thought of as ways to configure Envoy, but they approach configuration differently, and address different use cases.

Istio’s service mesh model is intended to provide security, traffic direction, and insight within the cluster (east-west traffic) and between the cluster and the outside world (north-south traffic).

Contour focuses on north-south traffic only – on making Envoy available to Kubernetes users as a simple, reliable load balancing solution.

How We Work

Mon, 01 Jan 0001 00:00:00 +0000

This page captures how we work on Contour.

Github Issue Management

When you pick up an issue, assign it to yourself. When you stop working, unassign yourself. While you hold an issue, you are responsible for giving status reports on it; over communicate, don’t let others speak for you, or worse, guess.
Don’t work on an issue assigned to someone else. If you think they’re over committed or stuck, please ask.

Security Report Process

Mon, 01 Jan 0001 00:00:00 +0000

Contour is a growing community devoted in creating the most secure, performant, scalable, and available ingress controller for Kubernetes. The community has adopted this security disclosure and response policy to ensure we responsibly handle critical issues.

Supported Versions

The Contour project maintains the following document on the release process and support matrix. Please refer to it for release related details.

Reporting a Vulnerability - Private Disclosure Process

Security is of the highest importance and all security vulnerabilities or suspected security vulnerabilities should be reported to Contour privately, to minimize attacks against current users of Contour before they are fixed. Vulnerabilities will be investigated and patched on the next patch (or minor) release as soon as possible. This information could be kept entirely internal to the project.

Security Response Checklist

Mon, 01 Jan 0001 00:00:00 +0000

This document outlines a checklist for Contour security team members (at time of writing, this is the same people as the maintainer team) to step through in the event Contour has a CVE that needs to be mitigated.

A CVE has been reported, what do I do?

User discovers a vulnerability and notifies cncf-contour-maintainers@lists.cncf.io
Contour maintainer team triages the vulnerability with the reporter and decide patch releases (multiple minors could be impacted) as well as downstream distributors.
Create a Security Advisory Draft on github Contour repo https://github.com/projectcontour/contour/security/advisories
- Requires patched versions
- As part of this, fill out the CVSS score and CWE enumerator, and request a CVE ID via Github.
Create a private fork for the Security Advisory using the Advisory page, and ensure everyone who needs to can see it.
Do not publish draft, keeping it in draft mode until we release patch
- Remember to give credit to the reporter, they can however remain anonymous or keep their company info private if they wish
Communicate to the reporter that draft is created & awaiting for precise dates for releases

Send email to the Distributors ( cncf-contour-distributors-announce@lists.cncf.io) mailing list on disclosure and patch releases dates, can include

Learn from previous mistakes, send this through the web interface at https://lists.cncf.io/g/cncf-contour-distributors-announce/ ! Don’t use a client that may “correct” the address to another one for you.
Description of vulnerability
Contour versions affected
Known attack vectors
Possible workarounds
Next step including patch releases
Leave out the CVE ID
Get buy-in from the distributors on release date, or at least see if there are objections

Post the Embargo note (sourced from https://projectcontour.io/resources/security-process/) at the bottom

The information that members receive on the Contour Distributors mailing list must not be made public, shared, or even hinted at anywhere beyond those who need to know within your specific team, unless you receive explicit approval to do so from the Contour Security Team. This remains true until the public disclosure date/time agreed upon by the list. Members of the list and others cannot use the information for any reason other than to get the issue fixed for your respective distribution's users.
Before you share any information from the list with members of your team who are required to fix the issue, these team members must agree to the same terms, and only be provided with information on a need-to-know basis.

In the unfortunate event that you share information beyond what is permitted by this policy, you must urgently inform the [Contour Security Team](https://projectcontour.io/resources/security-process#mailing-lists) of exactly what information was leaked and to whom. If you continue to leak information and break the policy outlined here, you will be permanently removed from the list.

Add #security tag to message

Release patches for all supported minors
- Submit PRs for fixes with pithy commit messages, or even no commit message. The point is to ensure that we don’t give away the CVE before the public release in a commit message.
When all patches are released and the embargo date is reached, publish the security advisory which was in draft mode.
Can now send above email to the broader public Contour users mailing list as well
Follow up on cncf-contour-distributors-announce@lists.cncf.io as well notifying users that releases are out
Do a team retrospective on the release for the CVE if applicable

Upgrading Contour

Mon, 01 Jan 0001 00:00:00 +0000

This document describes the changes needed to upgrade your Contour installation.

Before you start

Contour currently only tests sequential upgrades, i.e. without skipping any minor or patch versions. This approach is recommended for users in order to minimize downtime and avoid any potential issues. If you choose to skip versions while upgrading, please note that this may lead to additional downtime.

Resources on Contour

Compatibility Matrix

Compatibility Matrix

Notes on Compatibility

Contour Adopters

Success Stories

Contour Deprecation Policy

projectcontour.io API groups (aka Contour CRDs)

Contour Ecosystem

Related Projects

Plugins

Documents

Contour Philosophy

Non Goals

Contour Release Process

Minor Release Process

Overview

Process

Set environment variables

Contour Support Policy

Supported releases

Contour Tagging Policy

Released versions

Latest

Contour Threat Model and Security Posture

Reporting Security issues

Inputs

Expected Users

Contributing Technical Documentation

Contour Technical Documentation Contributing Guide

Frequently Asked Questions

Q: What’s the relationship between Contour and Istio?

How We Work

Github Issue Management

Security Report Process

Supported Versions

Reporting a Vulnerability - Private Disclosure Process

Security Response Checklist

A CVE has been reported, what do I do?

Upgrading Contour

Before you start

`projectcontour.io` API groups (aka Contour CRDs)