kubernetes
/
website
mirror of https://github.com/kubernetes/website.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

fix double bullets in TOC (#9175)

pull/9576/head
makocchi 2018-07-19 09:40:42 +09:00 committed by k8s-ci-robot
parent 9317dcfff0
commit bac30c0774
1 changed files with 13 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

17
content/en/docs/reference/using-api/deprecation-policy.md
View File

@ -4,17 +4,21 @@ reviewers:
- lavalamp - lavalamp
- thockin - thockin
title: Kubernetes Deprecation Policy title: Kubernetes Deprecation Policy
content_template: templates/concept
weight: 40 weight: 40
--- ---
{{% capture overview %}}
This document details the deprecation policy for various facets of the system.
{{% /capture %}}
{{% capture body %}}
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 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, 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 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. 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 ## Deprecating parts of the API
Since Kubernetes is an API-driven system, the API has evolved over time to 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
can not be removed from that version or have its behavior significantly can not be removed from that version or have its behavior significantly
changed, regardless of track. changed, regardless of track.
Note: For historical reasons, there are 2 "monolithic" API groups - "core" (no {{< note >}}
**Note:** For historical reasons, there are 2 "monolithic" API groups - "core" (no
group name) and "extensions". Resources will incrementally be moved from these group name) and "extensions". Resources will incrementally be moved from these
legacy API groups into more domain-specific API groups. legacy API groups into more domain-specific API groups.
{{< /note >}}
**Rule #2: API objects must be able to round-trip between API versions in a given **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 release without information loss, with the exception of whole REST resources
@ -83,11 +89,13 @@ no less than:**
This covers the maximum supported version skew of 2 releases. This covers the maximum supported version skew of 2 releases.
NOTE: Until [#52185](https://github.com/kubernetes/kubernetes/issues/52185) is {{< note >}}
**Note:** Until [#52185](https://github.com/kubernetes/kubernetes/issues/52185) is
resolved, no API versions that have been persisted to storage may be removed. resolved, no API versions that have been persisted to storage may be removed.
Serving REST endpoints for those versions may be disabled (subject to the Serving REST endpoints for those versions may be disabled (subject to the
deprecation timelines in this document), but the API server must remain capable deprecation timelines in this document), but the API server must remain capable
of decoding/converting previously persisted data from storage. of decoding/converting previously persisted data from storage.
{{< /note >}}
**Rule #4b: The "preferred" API version and the "storage version" for a given **Rule #4b: The "preferred" API version and the "storage version" for a given
group may not advance until after a release has been made that supports both the 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
mind that Kubernetes is committed to being a stable system that, as much as 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 possible, never breaks users. Exceptions will always be announced in all
relevant release notes. relevant release notes.
{{% /capture %}}