Skip to content

Commit d6636e5

Browse files
authored
Merge pull request #24474 from sftim/20201010_clarify_api_versions_redux
Tweak docs about Kubernetes API versions
2 parents 480d1df + 4e0b662 commit d6636e5

File tree

1 file changed

+39
-19
lines changed

1 file changed

+39
-19
lines changed

content/en/docs/concepts/overview/kubernetes-api.md

Lines changed: 39 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -77,19 +77,10 @@ about this format, see the [Kubernetes Protobuf serialization](https://github.co
7777
Interface Definition Language (IDL) files for each schema located in the Go
7878
packages that define the API objects.
7979

80-
## API changes
80+
## Persistence
8181

82-
Any system that is successful needs to grow and change as new use cases emerge or existing ones change.
83-
Therefore, Kubernetes has designed its features to allow the Kubernetes API to continuously change and grow.
84-
The Kubernetes project aims to _not_ break compatibility with existing clients, and to maintain that
85-
compatibility for a length of time so that other projects have an opportunity to adapt.
86-
87-
In general, new API resources and new resource fields can be added often and frequently.
88-
Elimination of resources or fields requires following the
89-
[API deprecation policy](/docs/reference/using-api/deprecation-policy/).
90-
91-
What constitutes a compatible change, and how to change the API, are detailed in
92-
[API changes](https://git.k8s.io/community/contributors/devel/sig-architecture/api_changes.md#readme).
82+
Kubernetes stores the serialized state of objects by writing them into
83+
{{< glossary_tooltip term_id="etcd" >}}.
9384

9485
## API groups and versioning
9586

@@ -107,17 +98,44 @@ To make it easier to evolve and to extend its API, Kubernetes implements
10798
[enabled or disabled](/docs/reference/using-api/#enabling-or-disabling).
10899

109100
API resources are distinguished by their API group, resource type, namespace
110-
(for namespaced resources), and name. The API server may serve the same
111-
underlying data through multiple API version and handle the conversion between
112-
API versions transparently. All these different versions are actually
113-
representations of the same resource. For example, suppose there are two
114-
versions `v1` and `v1beta1` for the same resource. An object created by the
115-
`v1beta1` version can then be read, updated, and deleted by either the
116-
`v1beta1` or the `v1` versions.
101+
(for namespaced resources), and name. The API server handles the conversion between
102+
API versions transparently: all the different versions are actually representations
103+
of the same persisted data. The API server may serve the same underlying data
104+
through multiple API versions.
105+
106+
For example, suppose there are two API versions, `v1` and `v1beta1`, for the same
107+
resource. If you originally created an object using the `v1beta1` version of its
108+
API, you can later read, update, or delete that object
109+
using either the `v1beta1` or the `v1` API version.
110+
111+
### API changes
112+
113+
Any system that is successful needs to grow and change as new use cases emerge or existing ones change.
114+
Therefore, Kubernetes has designed the Kubernetes API to continuously change and grow.
115+
The Kubernetes project aims to _not_ break compatibility with existing clients, and to maintain that
116+
compatibility for a length of time so that other projects have an opportunity to adapt.
117+
118+
In general, new API resources and new resource fields can be added often and frequently.
119+
Elimination of resources or fields requires following the
120+
[API deprecation policy](/docs/reference/using-api/deprecation-policy/).
121+
122+
Kubernetes makes a strong commitment to maintain compatibility for official Kubernetes APIs
123+
once they reach general availability (GA), typically at API version `v1`. Additionally,
124+
Kubernetes keeps compatibility even for _beta_ API versions wherever feasible:
125+
if you adopt a beta API you can continue to interact with your cluster using that API,
126+
even after the feature goes stable.
127+
128+
{{< note >}}
129+
Although Kubernetes also aims to maintain compatibility for _alpha_ APIs versions, in some
130+
circumstances this is not possible. If you use any alpha API versions, check the release notes
131+
for Kubernetes when upgrading your cluster, in case the API did change.
132+
{{< /note >}}
117133

118134
Refer to [API versions reference](/docs/reference/using-api/#api-versioning)
119135
for more details on the API version level definitions.
120136

137+
138+
121139
## API Extension
122140

123141
The Kubernetes API can be extended in one of two ways:
@@ -135,3 +153,5 @@ The Kubernetes API can be extended in one of two ways:
135153
how the cluster manages authentication and authorization for API access.
136154
- Learn about API endpoints, resource types and samples by reading
137155
[API Reference](/docs/reference/kubernetes-api/).
156+
- Learn about what constitutes a compatible change, and how to change the API, from
157+
[API changes](https://git.k8s.io/community/contributors/devel/sig-architecture/api_changes.md#readme).

0 commit comments

Comments
 (0)