Professional Documents
Culture Documents
The Kubernetes API - Kubernetes
The Kubernetes API - Kubernetes
The Kubernetes API - Kubernetes
HOMESETUPCONCEPTSTASKSTUTORIALSREFERENCECONTRIBUTE
Search
API endpoints, resource types and samples are described in API Reference.
Remote access to the API is discussed in the Controlling API Access doc.
The Kubernetes API also serves as the foundation for the declarative con@guration schema for
the system. The kubectl command-line tool can be used to create, update, delete, and get API
objects.
Kubernetes also stores its serialized state (currently in etcd) in terms of the API resources.
Kubernetes itself is decomposed into multiple components, which interact through its API.
API changes
OpenAPI and Swagger de>nitions
API versioning
API groups
Enabling API groups
Enabling resources in the groups
API changes
In our experience, any system that is successful needs to grow and change as new use cases
emerge or existing ones change. Therefore, we expect the Kubernetes API to continuously
change and grow. However, we intend to not break compatibility with existing clients, for an
extended period of time. In general, new API resources and new resource @elds can be
expected to be added frequently. Elimination of resources or @elds will require following the
API deprecation policy.
What constitutes a compatible change and how to change the API are detailed by the API
change document.
Starting with Kubernetes 1.10, the Kubernetes API server serves an OpenAPI spec via the
/openapi/v2 endpoint. The requested format is speci@ed by setting HTTP headers:
application/json ,
Accept application/com.github.proto-openapi.spec.v2@v1.0+protobuf
(the default content-type is application/json for */* or not passing this header)
Accept-
Encoding gzip (not passing this header is acceptable)
different formats. These endpoints are deprecated, and are removed in Kubernetes 1.14.
GET /swagger-2.0.0.pb-
GET /openapi/v2 Accept: application/com.github.proto-openapi.spec.v2@v1.0+protobuf
v1
Kubernetes implements an alternative Protobuf based serialization format for the API that is
primarily intended for intra-cluster communication, documented in the design proposal and
the IDL @les for each schema are located in the Go packages that de@ne the API objects.
Prior to 1.14, the Kubernetes apiserver also exposes an API that can be used to retrieve the
Swagger v1.2 Kubernetes API spec at /swaggerapi . This endpoint is deprecated, and will
be removed in Kubernetes 1.14.
API versioning
/apis/extensions/v1beta1 .
We chose to version at the API level rather than at the resource or @eld level to ensure that the
API presents a clear, consistent view of system resources and behavior, and to enable
controlling access to end-of-life and/or experimental APIs. The JSON and Protobuf
serialization schemas follow the same guidelines for schema changes - all descriptions below
cover both formats.
Note that API versioning and Software versioning are only indirectly related. The API and
release versioning proposal describes the relationship between API versioning and software
versioning.
Different API versions imply different levels of stability and support. The criteria for each level
are described in more detail in the API Changes documentation. They are summarized here:
Alpha level:
May be buggy. Enabling the feature may expose bugs. Disabled by default.
The API may change in incompatible ways in a later software release without notice.
Recommended for use only in short-lived testing clusters, due to increased risk of
bugs and lack of long-term support.
Beta level:
Code is well tested. Enabling the feature is considered safe. Enabled by default.
Support for the overall feature will not be dropped, though details may change.
Please do try our beta features and give feedback on them! Once they exit beta, it
may not be practical for us to make more changes.
Stable level:
Stable versions of features will appear in released software for many subsequent
versions.
API groups
To make it easier to extend the Kubernetes API, we implemented API groups. The API group is
speci@ed in a REST path and in the apiVersion @eld of a serialized object.
1. The core group, often referred to as the legacy group, is at the REST path /api/v1 and
uses apiVersion: v1 .
There are two supported paths to extending the API with custom resources:
2. Users needing the full set of Kubernetes API semantics can implement their own
apiserver and use the aggregator to make it seamless for clients.
Certain resources and API groups are enabled by default. They can be enabled or disabled by
setting --runtime-config on apiserver. --runtime-config accepts comma separated
values. For ex: to disable batch/v1, set --runtime-config=batch/v1=false , to enable
batch/v2alpha1, set --runtime-config=batch/v2alpha1 . The ]ag accepts comma
separated set of key=value pairs describing runtime con@guration of the apiserver.
Feedback
Page last modiSed on May 30, 2019 at 3:06 AM PST by Fix OpenAPI deprecated endpoints in
Kubernetes 1.14 (#14608) (Page History)
Home
Blog
Partners
Community
Case Studies
Contribute