Contour Deprecation Policy

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 the same rules as Kubernetes:

  • API elements may only be removed by incrementing the version of the API group.
  • An API version in a given track may not be deprecated until a new API version at least as stable is released.
Sample Version Tag State Deprecation timeframe Notes
v1alpha1 Alpha Any time Behavior can change any time, Fields can be removed at any time
v1beta1 Beta 1 release Behavior can change any time, fields won’t be removed without a version bump (ie v1alpha1 to v1alpha2)
v1 GA 1 year No fields will be removed, no behavior will substantially change. Fields can be added.

projectcontour.io CRD helper code

The projectcontour.io CRDs contain some helper code, for accessing various parts of the Go structs inside.

The API guarantees apply here as well, in the following way:

Sample Version Tag State Change/Deprecation timeframe Notes
v1alpha1 Alpha Any time Function and method signatures can change any time. Implementation may change any time.
v1beta1 Beta 1 release Function and method signatures won’t change without a version bump. Implementation may change any time.
v1 GA 1 year Function and method signatures won’t change without a version bump. Implementation may change any time, but behavior changes must be restricted to minor ones (that is, you can change how a return value is made, but not what it means)

Contour command line arguments

Because removing command line arguments is a breaking operation (that is, the program won’t start without them), Contour is committed to a gradual transition for changes here.

We try to use the following cycle for arguments:

  • Argument is announced deprecated, with a timeline for removal. This timeframe must never be shorter than 3 releases, but may be longer if required.
  • At the same time, Argument has a warning added, saying that it’s deprecated.
  • We wait the timeline period
  • The argument is removed.

Configuration file settings

We use the following cycle for config file settings:

  • Setting is announced deprecated, with a plan for how the functionality will be moved or removed, and a timeline.
  • Warning log added for deprecated setting.
  • We wait the timeline period
  • The setting is moved or removed.
Ready to try Contour?

Read our getting started documentation.