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.ioAPI groups (aka Contour CRDs)
Our Kubernetes CRDs use the Kubernetes API deprecation conventions, including a similar deprecation timeline.
We use the same rules as Kubernetes:
|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
|v1||GA||1 year||No fields will be removed, no behavior will substantially change. Fields can be added.|
projectcontour.ioCRD helper code
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)|
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:
We use the following cycle for config file settings:
Removing/Renaming metrics is a breaking change as it might cause alerts/ dashboards to break for operators.
We try to use the following cycle for deprecating metrics: