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

Merge pull request #24474 from sftim/20201010_clarify_api_versions_redux 

Tweak docs about Kubernetes API versions
pull/25376/head
Kubernetes Prow Robot 2020-12-03 08:51:00 -08:00 committed by GitHub
parent 480d1df9db 4e0b662954
commit d6636e50c2
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 39 additions and 19 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

58
content/en/docs/concepts/overview/kubernetes-api.md
View File

@ -77,19 +77,10 @@ about this format, see the [Kubernetes Protobuf serialization](https://github.co
Interface Definition Language (IDL) files for each schema located in the Go Interface Definition Language (IDL) files for each schema located in the Go
packages that define the API objects. packages that define the API objects.
## API changes ## Persistence
Any system that is successful needs to grow and change as new use cases emerge or existing ones change. Kubernetes stores the serialized state of objects by writing them into
Therefore, Kubernetes has designed its features to allow the Kubernetes API to continuously change and grow. {{< glossary_tooltip term_id="etcd" >}}.
The Kubernetes project aims to _not_ break compatibility with existing clients, and to maintain that
compatibility for a length of time so that other projects have an opportunity to adapt.
In general, new API resources and new resource fields can be added often and frequently.
Elimination of resources or fields requires following the
[API deprecation policy](/docs/reference/using-api/deprecation-policy/).
What constitutes a compatible change, and how to change the API, are detailed in
[API changes](https://git.k8s.io/community/contributors/devel/sig-architecture/api_changes.md#readme).
## API groups and versioning ## API groups and versioning
@ -107,17 +98,44 @@ To make it easier to evolve and to extend its API, Kubernetes implements
[enabled or disabled](/docs/reference/using-api/#enabling-or-disabling). [enabled or disabled](/docs/reference/using-api/#enabling-or-disabling).
API resources are distinguished by their API group, resource type, namespace API resources are distinguished by their API group, resource type, namespace
(for namespaced resources), and name. The API server may serve the same (for namespaced resources), and name. The API server handles the conversion between
underlying data through multiple API version and handle the conversion between API versions transparently: all the different versions are actually representations
API versions transparently. All these different versions are actually of the same persisted data. The API server may serve the same underlying data
representations of the same resource. For example, suppose there are two through multiple API versions.
versions `v1` and `v1beta1` for the same resource. An object created by the
`v1beta1` version can then be read, updated, and deleted by either the For example, suppose there are two API versions, `v1` and `v1beta1`, for the same
`v1beta1` or the `v1` versions. resource. If you originally created an object using the `v1beta1` version of its
API, you can later read, update, or delete that object
using either the `v1beta1` or the `v1` API version.
### API changes
Any system that is successful needs to grow and change as new use cases emerge or existing ones change.
Therefore, Kubernetes has designed the Kubernetes API to continuously change and grow.
The Kubernetes project aims to _not_ break compatibility with existing clients, and to maintain that
compatibility for a length of time so that other projects have an opportunity to adapt.
In general, new API resources and new resource fields can be added often and frequently.
Elimination of resources or fields requires following the
[API deprecation policy](/docs/reference/using-api/deprecation-policy/).
Kubernetes makes a strong commitment to maintain compatibility for official Kubernetes APIs
once they reach general availability (GA), typically at API version `v1`. Additionally,
Kubernetes keeps compatibility even for _beta_ API versions wherever feasible:
if you adopt a beta API you can continue to interact with your cluster using that API,
even after the feature goes stable.
{{< note >}}
Although Kubernetes also aims to maintain compatibility for _alpha_ APIs versions, in some
circumstances this is not possible. If you use any alpha API versions, check the release notes
for Kubernetes when upgrading your cluster, in case the API did change.
{{< /note >}}
Refer to [API versions reference](/docs/reference/using-api/#api-versioning) Refer to [API versions reference](/docs/reference/using-api/#api-versioning)
for more details on the API version level definitions. for more details on the API version level definitions.
## API Extension ## API Extension
The Kubernetes API can be extended in one of two ways: 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:
how the cluster manages authentication and authorization for API access. how the cluster manages authentication and authorization for API access.
- Learn about API endpoints, resource types and samples by reading - Learn about API endpoints, resource types and samples by reading
[API Reference](/docs/reference/kubernetes-api/). [API Reference](/docs/reference/kubernetes-api/).
- Learn about what constitutes a compatible change, and how to change the API, from
[API changes](https://git.k8s.io/community/contributors/devel/sig-architecture/api_changes.md#readme).