The overall API conventions for Kubernetes are described in the API conventions doc. Associated API endpoints, resource types, and example usage can be found in the API reference. Kubernetes itself is decomposed into multiple components, which interact with one another through the API.

API Changes

All successful systems need to grow and change as new use cases emerge and existing ones change. It is expected that the Kubernetes API will continually change and grow; however, client API compatibility should not break. In general, new API resources and fields can be expected to be added frequently, while the removal of resources and fields will follow an official API deprecation policy.

All information in regards to API changes are detailed in the API change document.

Open API and Swagger

The complete API documentation is available using Swagger v1.2 as well as OpenAPI. The Swagger API spec is exposed via the Kubernetes apiserver at /swaggerapi . You can also choose to enable a UI to browse documentation at /swagger-ui by passing the --enable-swagger-ui=true flag to the apiserver.

As of Kubernetes 1.4, the OpenApi spec is also available at the /swagger.json route.

An alternative Protobuf based serialization format for the API is also implemented primarily for intra-cluster communication. It has a documented design proposal and the associated IDL files are located in the Go packages which define the API objects.

API Versioning

In an effort to make it easier to eliminate fields and restructure resources, Kubernetes supports multiple API versions, each located at different API paths such as /api/v1 or /apis/extensions/v1beta1 .

Versioning happens at the API level rather than at the resource level to ensure that the API presents a clear and consistent view of system behavior, and enables access control to deprecated or experimental APIs. The JSON and Protobuf serialization schemas follow the same change guidelines.

Different API versions imply varying levels of stability and support, which are summarized below:


  • The version name contains alpha (for example, v1alpha1 ).
  • Enabling this feature may introduce bugs, and as such, will be disabled by default.
  • Support for the feature may be dropped at any time, without notice.
  • The API may change in incompatible ways in later releases, without notice.
  • Only recommended for short-term testing due to increased risk of bugs and lack of long-term support.


  • The version name containers beta  (for example, v2beta3 ).
  • Code is well tested and considered safe to run. It is enabled by default.
  • Support for the feature will not be dropped although implementation details may change.
  • The schema and object semantics may change in incompatible ways in a subsequent beta or stable release. Instructions for migration to the next version will be provided. Downtime may be required for resources that rely on this feature.
  • Only recommended for non-business-critical use cases given the potential for incompatible changes. 


  • The version name is vX  where x  is an integer.
  • Stale versions of features will appear in subsequently released versions of the software.

API Groups

In an effort to make extending the Kubernetes API easier, API groups were implemented. The API group is specified as a portion of the REST path, as well as in the apiVersion field of a serialized object.

There are several API groups actively used:

  • Core  - often referred to as the legacy group, uses apiVersion: v1 and uses the REST path /api/v1 
  • Named - named groups use apiVersion: $GROUP_NAME/$VERSION (for example: apiVersion: batch/v1 ), and use the REST path /apis/$GROUP_NAME/$VERSION

It is possible to extend the API through the use of custom resources

While certain resources and API groups are enabled by default, they can be toggled on or off by setting the --runtime-config  on the apiserver. The flag accepts a comma delimited list of values. For example, to disable the batch/v1  group, set --runtime-config=batch/v1=false  and to enable batch/v2alpha1 , set --runtime-config=batch/v2alpha1 .

It is important to remember that enabling or disabling groups require restarting the apiserver and controller manager in order to pick up the changes.

Did this answer your question?