@@ -77,19 +77,10 @@ about this format, see the [Kubernetes Protobuf serialization](https://github.co
77
77
Interface Definition Language (IDL) files for each schema located in the Go
78
78
packages that define the API objects.
79
79
80
- ## API changes
80
+ ## Persistence
81
81
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" >}}.
93
84
94
85
## API groups and versioning
95
86
@@ -107,17 +98,44 @@ To make it easier to evolve and to extend its API, Kubernetes implements
107
98
[ enabled or disabled] ( /docs/reference/using-api/#enabling-or-disabling ) .
108
99
109
100
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 >}}
117
133
118
134
Refer to [ API versions reference] ( /docs/reference/using-api/#api-versioning )
119
135
for more details on the API version level definitions.
120
136
137
+
138
+
121
139
## API Extension
122
140
123
141
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:
135
153
how the cluster manages authentication and authorization for API access.
136
154
- Learn about API endpoints, resource types and samples by reading
137
155
[ 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