@@ -4,17 +4,21 @@ reviewers:
4
4
- lavalamp
5
5
- thockin
6
6
title : Kubernetes Deprecation Policy
7
+ content_template : templates/concept
7
8
weight : 40
8
9
---
9
10
11
+ {{% capture overview %}}
12
+ This document details the deprecation policy for various facets of the system.
13
+ {{% /capture %}}
14
+
15
+ {{% capture body %}}
10
16
Kubernetes is a large system with many components and many contributors. As
11
17
with any such software, the feature set naturally evolves over time, and
12
18
sometimes a feature may need to be removed. This could include an API, a flag,
13
19
or even an entire feature. To avoid breaking existing users, Kubernetes follows
14
20
a deprecation policy for aspects of the system that are slated to be removed.
15
21
16
- This document details the deprecation policy for various facets of the system.
17
-
18
22
## Deprecating parts of the API
19
23
20
24
Since Kubernetes is an API-driven system, the API has evolved over time to
@@ -52,9 +56,11 @@ Once an API element has been added to an API group at a particular version, it
52
56
can not be removed from that version or have its behavior significantly
53
57
changed, regardless of track.
54
58
55
- Note: For historical reasons, there are 2 "monolithic" API groups - "core" (no
59
+ {{< note >}}
60
+ ** Note:** For historical reasons, there are 2 "monolithic" API groups - "core" (no
56
61
group name) and "extensions". Resources will incrementally be moved from these
57
62
legacy API groups into more domain-specific API groups.
63
+ {{< /note >}}
58
64
59
65
** Rule #2 : API objects must be able to round-trip between API versions in a given
60
66
release without information loss, with the exception of whole REST resources
@@ -83,11 +89,13 @@ no less than:**
83
89
84
90
This covers the maximum supported version skew of 2 releases.
85
91
86
- NOTE: Until [ #52185 ] ( https://github.com/kubernetes/kubernetes/issues/52185 ) is
92
+ {{< note >}}
93
+ ** Note:** Until [ #52185 ] ( https://github.com/kubernetes/kubernetes/issues/52185 ) is
87
94
resolved, no API versions that have been persisted to storage may be removed.
88
95
Serving REST endpoints for those versions may be disabled (subject to the
89
96
deprecation timelines in this document), but the API server must remain capable
90
97
of decoding/converting previously persisted data from storage.
98
+ {{< /note >}}
91
99
92
100
** Rule #4b: The "preferred" API version and the "storage version" for a given
93
101
group may not advance until after a release has been made that supports both the
@@ -367,3 +375,4 @@ leaders to find the best solutions for those specific cases, always bearing in
367
375
mind that Kubernetes is committed to being a stable system that, as much as
368
376
possible, never breaks users. Exceptions will always be announced in all
369
377
relevant release notes.
378
+ {{% /capture %}}
0 commit comments