Skip to content

Commit d485f2e

Browse files
thockingeojaz
thockin
authored and
geojaz
committed
Add deprecation policy (kubernetes#1856)
1 parent 35a7d82 commit d485f2e

File tree

1 file changed

+186
-0
lines changed

1 file changed

+186
-0
lines changed

‎docs/deprecation-policy.md

+186
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,186 @@
1+
---
2+
assignees:
3+
- bgrant0607
4+
- lavalamp
5+
- thockin
6+
7+
---
8+
9+
# Kubernetes Deprecation Policy
10+
11+
Kubernetes is a large system with many components and many contributors.  As
12+
with any such software, the feature set naturally evolves over time, and
13+
sometimes a feature may need to be removed. This could include an API, a flag,
14+
or even an entire feature. To avoid breaking existing users, Kubernetes follows
15+
a deprecation policy for aspects of the system that are slated to be removed.
16+
17+
This document details the deprecation policy for various facets of the system.
18+
19+
## Deprecating parts of the API
20+
21+
Since Kubernetes is an API-driven system, the API has evolved over time to
22+
reflect the evolving understanding of the problem space. The Kubernetes API is
23+
actually a set of APIs, called “API groups”, and each API group is
24+
independently versioned. [API versions](http://kubernetes.io/docs/api/) fall
25+
into 3 main tracks, each of which has different policies for deprecation:
26+
27+
| Example | Track |
28+
|----------|----------------------------------|
29+
| v1 | GA (generally available, stable) |
30+
| v1beta1 | Beta (pre-release) |
31+
| v1alpha1 | Alpha (experimental) |
32+
33+
A given release of Kubernetes can support any number of API groups and any
34+
number of versions of each.
35+
36+
The following rules govern the deprecation of elements of the API.  This
37+
includes:
38+
39+
* REST resources (aka API objects)
40+
* Fields of REST resources
41+
* Enumerated or constant values
42+
* Component config structures
43+
44+
These rules are enforced between official releases, not between
45+
arbitrary commits to master or release branches.
46+
47+
**Rule #1: API elements may only be removed by incrementing the version of the
48+
API group.**
49+
50+
Once an API element has been added to an API group at a particular version, it
51+
can not be removed from that version or have its behavior significantly
52+
changed, regardless of track.
53+
54+
Note: For historical reasons, there are 2 “monolithic” API groups - “core” (no
55+
group name) and “extensions”.  Resources will incrementally be moved from these
56+
legacy API groups into more domain-specific API groups.
57+
58+
**Rule #2: API objects must be able to round-trip between API versions in a given
59+
release without information loss, with the exception of whole REST resources
60+
that do not exist in some versions.**
61+
62+
For example, an object can be written as v1 and then read back as v2 and
63+
converted to v1, and the resulting v1 resource will be identical to the
64+
original.  The representation in v2 might be different from v1, but the system
65+
knows how to convert between them in both directions. Additionally, any new
66+
field added in v2 must be able to round-trip to v1 and back, which means v1
67+
might have to add an equivalent field or represent it as an annotation.
68+
69+
**Rule #3: An API version in a given track may not be deprecated until a new
70+
API version at least as stable is released.**
71+
72+
GA API versions can replace GA API versions as well as beta and alpha API
73+
version. Beta API versions *may not* replace GA API versions.
74+
75+
**Rule #4: Other than the most recent API version in each track, older API
76+
versions must be supported after their announced deprecation for a duration of
77+
no less than:**
78+
* **GA: 1 year or 2 releases (whichever is longer)**
79+
* **Beta: 3 months or 1 release (whichever is longer)**
80+
* **Alpha: 0 releases**
81+
82+
This is best illustrated by example.  Imagine a Kubernetes release, version X,
83+
which supports a particular API group.  A new Kubernetes release is made every
84+
approximately 3 months (4 per year).  The following table describes which API
85+
versions are supported in a series of subsequent releases.
86+
87+
| Release | API versions | Notes |
88+
|---------|--------------|-------|
89+
| X | v1 | |
90+
| X+1 | v1, v2alpha1 | |
91+
| X+2 | v1, v2alpha2 | * v2alpha1 is removed, “action required” relnote |
92+
| X+3 | v1, v2beta1 | * v2alpha2 is removed, “action required” relnote |
93+
| X+4 | v1, v2beta1, v2beta2 | * v2beta1 is deprecated, “action required” relnote |
94+
| X+5 | v1, v2, v2beta2 | * v2beta1 is removed, “action required” relnote<br> * v2beta2 is deprecated, “action required” relnote<br> * v1 is deprecated, “action required” relnote |
95+
| X+6 | v1, v2 | * v2beta2 is removed, “action required” relnote |
96+
| X+7 | v1, v2 | |
97+
| X+8 | v1, v2 | |
98+
| X+9 | v2 | * v1 is removed, “action required” relnote |
99+
100+
### REST resources (aka API objects)
101+
102+
Consider a hypothetical REST resource named Widget, which was present in API v1
103+
in the above timeline, and which needs to be deprecated.  We
104+
[document](http://kubernetes.io/docs/deprecated/) and
105+
[announce](https://groups.google.com/forum/#!forum/kubernetes-announce) the
106+
deprecation in sync with release X+1.  The Widget resource still exists in API
107+
version v1 (deprecated) but not in v2alpha1.  The Widget resource continues to
108+
exist and function in releases up to and including X+8.  Only in release X+9,
109+
when API v1 has aged out, does the Widget resource cease to exist, and the
110+
behavior get removed.
111+
112+
### Fields of REST resources
113+
114+
As with whole REST resources, an individual field which was present in API v1
115+
must exist and function until API v1 is removed.  Unlike whole resources, the
116+
v2 APIs may choose a different representation for the field, as long as it can
117+
be round-tripped.  For example a v1 field named “magnitude” which was
118+
deprecated might be named “deprecatedMagnitude” in API v2.  When v1 is
119+
eventually removed, the deprecated field can be removed from v2.
120+
121+
### Enumerated or constant values
122+
123+
As with whole REST resources and fields thereof, a constant value which was
124+
supported in API v1 must exist and function until API v1 is removed.
125+
126+
### Component config structures
127+
128+
Component configs are versioned and managed just like REST resources.
129+
130+
### Future work
131+
132+
Over time, Kubernetes will introduce more fine-grained API versions, at which
133+
point these rules will be adjusted as needed.
134+
135+
## Deprecating a flag or CLI
136+
137+
The Kubernetes system is comprised of several different programs cooperating.
138+
Sometimes, a Kubernetes release might remove flags or CLI commands
139+
(collectively “CLI elements”) in these programs.  The individual programs
140+
naturally sort into two main groups - user-facing and admin-facing programs,
141+
which vary slightly in their deprecation policies.  Unless a flag is explicitly
142+
prefixed or documented as “alpha” or “beta”, it is considered GA.
143+
144+
CLI elements are effectively part of the API to the system, but since they are
145+
not versioned in the same way as the REST API, the rules for deprecation are as
146+
follows:
147+
148+
**Rule #5a: CLI elements of user-facing components (e.g. kubectl) must function
149+
after their announced deprecation for no less than:**
150+
* **GA: 1 year or 2 releases (whichever is longer)**
151+
* **Beta: 3 months or 1 release (whichever is longer)**
152+
* **Alpha: 0 releases**
153+
154+
**Rule #5b: CLI elements of admin-facing components (e.g. kubelet) must function
155+
after their announced deprecation for no less than:**
156+
* **GA: 6 months or 1 release (whichever is longer)**
157+
* **Beta: 3 months or 1 release (whichever is longer)**
158+
* **Alpha: 0 releases**
159+
160+
**Rule #6: Deprecated CLI elements must emit warnings (optionally disableable)
161+
when used.**
162+
163+
## Deprecating a feature or behavior
164+
165+
Occasionally a Kubernetes release needs to deprecate some feature or behavior
166+
of the system that is not controlled by the API or CLI.  In this case, the
167+
rules for deprecation are as follows:
168+
169+
**Rule #7: Deprecated behaviors must function for no less than 1 year after their
170+
announced deprecation.**
171+
172+
This does not imply that all changes to the system are governed by this policy.
173+
This applies only to significant, user-visible behaviors which impact the
174+
correctness of applications running on Kubernetes or that impact the
175+
administration of Kubernetes clusters, and which are being removed entirely.
176+
177+
## Exceptions
178+
179+
No policy can cover every possible situation.  This policy is a living
180+
document, and will evolve over time.  In practice, there will be situations
181+
that do not fit neatly into this policy, or for which this policy becomes a
182+
serious impediment.  Such situations should be discussed with SIGs and project
183+
leaders to find the best solutions for those specific cases, always bearing in
184+
mind that Kubernetes is committed to being a stable system that, as much as
185+
possible, never breaks users. Exceptions will always be announced in all
186+
relevant release notes.

0 commit comments

Comments
 (0)