From 6ebd94302d6b758c3f7bc253a96d973573eaba20 Mon Sep 17 00:00:00 2001 From: Tim Hockin Date: Mon, 2 Jan 2017 23:43:12 -0800 Subject: [PATCH 1/2] Add deprecation policy (#1856) --- docs/deprecation-policy.md | 186 +++++++++++++++++++++++++++++++++++++ 1 file changed, 186 insertions(+) create mode 100644 docs/deprecation-policy.md diff --git a/docs/deprecation-policy.md b/docs/deprecation-policy.md new file mode 100644 index 0000000000..90ac6ad91d --- /dev/null +++ b/docs/deprecation-policy.md @@ -0,0 +1,186 @@ +--- +assignees: +- bgrant0607 +- lavalamp +- thockin + +--- + +# Kubernetes Deprecation Policy + +Kubernetes is a large system with many components and many contributors.  As +with any such software, the feature set naturally evolves over time, and +sometimes a feature may need to be removed. This could include an API, a flag, +or even an entire feature. To avoid breaking existing users, Kubernetes follows +a deprecation policy for aspects of the system that are slated to be removed. + +This document details the deprecation policy for various facets of the system. + +## Deprecating parts of the API + +Since Kubernetes is an API-driven system, the API has evolved over time to +reflect the evolving understanding of the problem space. The Kubernetes API is +actually a set of APIs, called “API groups”, and each API group is +independently versioned. [API versions](http://kubernetes.io/docs/api/) fall +into 3 main tracks, each of which has different policies for deprecation: + +| Example | Track | +|----------|----------------------------------| +| v1 | GA (generally available, stable) | +| v1beta1 | Beta (pre-release) | +| v1alpha1 | Alpha (experimental) | + +A given release of Kubernetes can support any number of API groups and any +number of versions of each. + +The following rules govern the deprecation of elements of the API.  This +includes: + + * REST resources (aka API objects) + * Fields of REST resources + * Enumerated or constant values + * Component config structures + +These rules are enforced between official releases, not between +arbitrary commits to master or release branches. + +**Rule #1: API elements may only be removed by incrementing the version of the +API group.** + +Once an API element has been added to an API group at a particular version, it +can not be removed from that version or have its behavior significantly +changed, regardless of track. + +Note: For historical reasons, there are 2 “monolithic” API groups - “core” (no +group name) and “extensions”.  Resources will incrementally be moved from these +legacy API groups into more domain-specific API groups. + +**Rule #2: API objects must be able to round-trip between API versions in a given +release without information loss, with the exception of whole REST resources +that do not exist in some versions.** + +For example, an object can be written as v1 and then read back as v2 and +converted to v1, and the resulting v1 resource will be identical to the +original.  The representation in v2 might be different from v1, but the system +knows how to convert between them in both directions. Additionally, any new +field added in v2 must be able to round-trip to v1 and back, which means v1 +might have to add an equivalent field or represent it as an annotation. + +**Rule #3: An API version in a given track may not be deprecated until a new +API version at least as stable is released.** + +GA API versions can replace GA API versions as well as beta and alpha API +version. Beta API versions *may not* replace GA API versions. + +**Rule #4: Other than the most recent API version in each track, older API +versions must be supported after their announced deprecation for a duration of +no less than:** + * **GA: 1 year or 2 releases (whichever is longer)** + * **Beta: 3 months or 1 release (whichever is longer)** + * **Alpha: 0 releases** + +This is best illustrated by example.  Imagine a Kubernetes release, version X, +which supports a particular API group.  A new Kubernetes release is made every +approximately 3 months (4 per year).  The following table describes which API +versions are supported in a series of subsequent releases. + +| Release | API versions | Notes | +|---------|--------------|-------| +| X | v1 | | +| X+1 | v1, v2alpha1 | | +| X+2 | v1, v2alpha2 | * v2alpha1 is removed, “action required” relnote | +| X+3 | v1, v2beta1 | * v2alpha2 is removed, “action required” relnote | +| X+4 | v1, v2beta1, v2beta2 | * v2beta1 is deprecated, “action required” relnote | +| X+5 | v1, v2, v2beta2 | * v2beta1 is removed, “action required” relnote
* v2beta2 is deprecated, “action required” relnote
* v1 is deprecated, “action required” relnote | +| X+6 | v1, v2 | * v2beta2 is removed, “action required” relnote | +| X+7 | v1, v2 | | +| X+8 | v1, v2 | | +| X+9 | v2 | * v1 is removed, “action required” relnote | + +### REST resources (aka API objects) + +Consider a hypothetical REST resource named Widget, which was present in API v1 +in the above timeline, and which needs to be deprecated.  We +[document](http://kubernetes.io/docs/deprecated/) and +[announce](https://groups.google.com/forum/#!forum/kubernetes-announce) the +deprecation in sync with release X+1.  The Widget resource still exists in API +version v1 (deprecated) but not in v2alpha1.  The Widget resource continues to +exist and function in releases up to and including X+8.  Only in release X+9, +when API v1 has aged out, does the Widget resource cease to exist, and the +behavior get removed. + +### Fields of REST resources + +As with whole REST resources, an individual field which was present in API v1 +must exist and function until API v1 is removed.  Unlike whole resources, the +v2 APIs may choose a different representation for the field, as long as it can +be round-tripped.  For example a v1 field named “magnitude” which was +deprecated might be named “deprecatedMagnitude” in API v2.  When v1 is +eventually removed, the deprecated field can be removed from v2. + +### Enumerated or constant values + +As with whole REST resources and fields thereof, a constant value which was +supported in API v1 must exist and function until API v1 is removed. + +### Component config structures + +Component configs are versioned and managed just like REST resources. + +### Future work + +Over time, Kubernetes will introduce more fine-grained API versions, at which +point these rules will be adjusted as needed. + +## Deprecating a flag or CLI + +The Kubernetes system is comprised of several different programs cooperating. +Sometimes, a Kubernetes release might remove flags or CLI commands +(collectively “CLI elements”) in these programs.  The individual programs +naturally sort into two main groups - user-facing and admin-facing programs, +which vary slightly in their deprecation policies.  Unless a flag is explicitly +prefixed or documented as “alpha” or “beta”, it is considered GA. + +CLI elements are effectively part of the API to the system, but since they are +not versioned in the same way as the REST API, the rules for deprecation are as +follows: + +**Rule #5a: CLI elements of user-facing components (e.g. kubectl) must function +after their announced deprecation for no less than:** + * **GA: 1 year or 2 releases (whichever is longer)** + * **Beta: 3 months or 1 release (whichever is longer)** + * **Alpha: 0 releases** + +**Rule #5b: CLI elements of admin-facing components (e.g. kubelet) must function +after their announced deprecation for no less than:** + * **GA: 6 months or 1 release (whichever is longer)** + * **Beta: 3 months or 1 release (whichever is longer)** + * **Alpha: 0 releases** + +**Rule #6: Deprecated CLI elements must emit warnings (optionally disableable) +when used.** + +## Deprecating a feature or behavior + +Occasionally a Kubernetes release needs to deprecate some feature or behavior +of the system that is not controlled by the API or CLI.  In this case, the +rules for deprecation are as follows: + +**Rule #7: Deprecated behaviors must function for no less than 1 year after their +announced deprecation.** + +This does not imply that all changes to the system are governed by this policy. +This applies only to significant, user-visible behaviors which impact the +correctness of applications running on Kubernetes or that impact the +administration of Kubernetes clusters, and which are being removed entirely. + +## Exceptions + +No policy can cover every possible situation.  This policy is a living +document, and will evolve over time.  In practice, there will be situations +that do not fit neatly into this policy, or for which this policy becomes a +serious impediment.  Such situations should be discussed with SIGs and project +leaders to find the best solutions for those specific cases, always bearing in +mind that Kubernetes is committed to being a stable system that, as much as +possible, never breaks users. Exceptions will always be announced in all +relevant release notes. From 476fbee3344bbb2137f0dd58144216d1e11e2677 Mon Sep 17 00:00:00 2001 From: Tim Hockin Date: Tue, 3 Jan 2017 00:28:28 -0800 Subject: [PATCH 2/2] Convert to pure ASCII (#2110) --- docs/deprecation-policy.md | 58 +++++++++++++++++++------------------- 1 file changed, 29 insertions(+), 29 deletions(-) diff --git a/docs/deprecation-policy.md b/docs/deprecation-policy.md index 90ac6ad91d..14db737d13 100644 --- a/docs/deprecation-policy.md +++ b/docs/deprecation-policy.md @@ -8,7 +8,7 @@ assignees: # Kubernetes Deprecation Policy -Kubernetes is a large system with many components and many contributors.  As +Kubernetes is a large system with many components and many contributors. As with any such software, the feature set naturally evolves over time, and sometimes a feature may need to be removed. This could include an API, a flag, or even an entire feature. To avoid breaking existing users, Kubernetes follows @@ -20,7 +20,7 @@ This document details the deprecation policy for various facets of the system. Since Kubernetes is an API-driven system, the API has evolved over time to reflect the evolving understanding of the problem space. The Kubernetes API is -actually a set of APIs, called “API groups”, and each API group is +actually a set of APIs, called "API groups", and each API group is independently versioned. [API versions](http://kubernetes.io/docs/api/) fall into 3 main tracks, each of which has different policies for deprecation: @@ -33,7 +33,7 @@ into 3 main tracks, each of which has different policies for deprecation: A given release of Kubernetes can support any number of API groups and any number of versions of each. -The following rules govern the deprecation of elements of the API.  This +The following rules govern the deprecation of elements of the API. This includes: * REST resources (aka API objects) @@ -51,8 +51,8 @@ Once an API element has been added to an API group at a particular version, it can not be removed from that version or have its behavior significantly changed, regardless of track. -Note: For historical reasons, there are 2 “monolithic” API groups - “core” (no -group name) and “extensions”.  Resources will incrementally be moved from these +Note: For historical reasons, there are 2 "monolithic" API groups - "core" (no +group name) and "extensions". Resources will incrementally be moved from these legacy API groups into more domain-specific API groups. **Rule #2: API objects must be able to round-trip between API versions in a given @@ -61,7 +61,7 @@ that do not exist in some versions.** For example, an object can be written as v1 and then read back as v2 and converted to v1, and the resulting v1 resource will be identical to the -original.  The representation in v2 might be different from v1, but the system +original. The representation in v2 might be different from v1, but the system knows how to convert between them in both directions. Additionally, any new field added in v2 must be able to round-trip to v1 and back, which means v1 might have to add an equivalent field or represent it as an annotation. @@ -79,43 +79,43 @@ no less than:** * **Beta: 3 months or 1 release (whichever is longer)** * **Alpha: 0 releases** -This is best illustrated by example.  Imagine a Kubernetes release, version X, -which supports a particular API group.  A new Kubernetes release is made every -approximately 3 months (4 per year).  The following table describes which API +This is best illustrated by example. Imagine a Kubernetes release, version X, +which supports a particular API group. A new Kubernetes release is made every +approximately 3 months (4 per year). The following table describes which API versions are supported in a series of subsequent releases. | Release | API versions | Notes | |---------|--------------|-------| | X | v1 | | | X+1 | v1, v2alpha1 | | -| X+2 | v1, v2alpha2 | * v2alpha1 is removed, “action required” relnote | -| X+3 | v1, v2beta1 | * v2alpha2 is removed, “action required” relnote | -| X+4 | v1, v2beta1, v2beta2 | * v2beta1 is deprecated, “action required” relnote | -| X+5 | v1, v2, v2beta2 | * v2beta1 is removed, “action required” relnote
* v2beta2 is deprecated, “action required” relnote
* v1 is deprecated, “action required” relnote | -| X+6 | v1, v2 | * v2beta2 is removed, “action required” relnote | +| X+2 | v1, v2alpha2 | * v2alpha1 is removed, "action required" relnote | +| X+3 | v1, v2beta1 | * v2alpha2 is removed, "action required" relnote | +| X+4 | v1, v2beta1, v2beta2 | * v2beta1 is deprecated, "action required" relnote | +| X+5 | v1, v2, v2beta2 | * v2beta1 is removed, "action required" relnote
* v2beta2 is deprecated, "action required" relnote
* v1 is deprecated, "action required" relnote | +| X+6 | v1, v2 | * v2beta2 is removed, "action required" relnote | | X+7 | v1, v2 | | | X+8 | v1, v2 | | -| X+9 | v2 | * v1 is removed, “action required” relnote | +| X+9 | v2 | * v1 is removed, "action required" relnote | ### REST resources (aka API objects) Consider a hypothetical REST resource named Widget, which was present in API v1 -in the above timeline, and which needs to be deprecated.  We +in the above timeline, and which needs to be deprecated. We [document](http://kubernetes.io/docs/deprecated/) and [announce](https://groups.google.com/forum/#!forum/kubernetes-announce) the -deprecation in sync with release X+1.  The Widget resource still exists in API -version v1 (deprecated) but not in v2alpha1.  The Widget resource continues to -exist and function in releases up to and including X+8.  Only in release X+9, +deprecation in sync with release X+1. The Widget resource still exists in API +version v1 (deprecated) but not in v2alpha1. The Widget resource continues to +exist and function in releases up to and including X+8. Only in release X+9, when API v1 has aged out, does the Widget resource cease to exist, and the behavior get removed. ### Fields of REST resources As with whole REST resources, an individual field which was present in API v1 -must exist and function until API v1 is removed.  Unlike whole resources, the +must exist and function until API v1 is removed. Unlike whole resources, the v2 APIs may choose a different representation for the field, as long as it can -be round-tripped.  For example a v1 field named “magnitude” which was -deprecated might be named “deprecatedMagnitude” in API v2.  When v1 is +be round-tripped. For example a v1 field named "magnitude" which was +deprecated might be named "deprecatedMagnitude" in API v2. When v1 is eventually removed, the deprecated field can be removed from v2. ### Enumerated or constant values @@ -136,10 +136,10 @@ point these rules will be adjusted as needed. The Kubernetes system is comprised of several different programs cooperating. Sometimes, a Kubernetes release might remove flags or CLI commands -(collectively “CLI elements”) in these programs.  The individual programs +(collectively "CLI elements") in these programs. The individual programs naturally sort into two main groups - user-facing and admin-facing programs, -which vary slightly in their deprecation policies.  Unless a flag is explicitly -prefixed or documented as “alpha” or “beta”, it is considered GA. +which vary slightly in their deprecation policies. Unless a flag is explicitly +prefixed or documented as "alpha" or "beta", it is considered GA. CLI elements are effectively part of the API to the system, but since they are not versioned in the same way as the REST API, the rules for deprecation are as @@ -163,7 +163,7 @@ when used.** ## Deprecating a feature or behavior Occasionally a Kubernetes release needs to deprecate some feature or behavior -of the system that is not controlled by the API or CLI.  In this case, the +of the system that is not controlled by the API or CLI. In this case, the rules for deprecation are as follows: **Rule #7: Deprecated behaviors must function for no less than 1 year after their @@ -176,10 +176,10 @@ administration of Kubernetes clusters, and which are being removed entirely. ## Exceptions -No policy can cover every possible situation.  This policy is a living -document, and will evolve over time.  In practice, there will be situations +No policy can cover every possible situation. This policy is a living +document, and will evolve over time. In practice, there will be situations that do not fit neatly into this policy, or for which this policy becomes a -serious impediment.  Such situations should be discussed with SIGs and project +serious impediment. Such situations should be discussed with SIGs and project leaders to find the best solutions for those specific cases, always bearing in mind that Kubernetes is committed to being a stable system that, as much as possible, never breaks users. Exceptions will always be announced in all