Kubernetes describes itself like so:

Kubernetes is an open source container orchestration engine for automating deployment, scaling, and management of containerized applications. The open source project is hosted by the Cloud Native Computing Foundation (CNCF).

An instance of Kubernetes is called a "cluster" and within such a cluster, resources are stored that describe the desired state of the world. A resource could for example be a ConfigMap, which can contain arbitrary configuration values that can then be consumed by applications in the cluster. All the resources available in a cluster are versioned and grouped based on their purpose and are considered the API of a Kubernetes cluster.

Kubernetes' cluster orchestration is based upon resources, which are defined in various API groups (based on their purpose, like apps for application management or rbac.authorization.k8s.io to manage permissions inside a Kubernetes cluster). Resources are often viewed and interacted with in the form of YAML and an example resource, a ConfigMap, could looke like this:

apiVersion: core/v1
kind: ConfigMap
metadata:
  name: my-app-config
data:
  database: "sql://user:pass@182.18.265.99:123/"
  theme: "dark"
  environment: "production"
            

To allow for these APIs to evolve over time, each API group defines a set of API versions. These follow a simple naming convention of vN followed by an optional maturity level (for example beta1), so an API could evolve like v1alpha1 –> v1beta1 –> v1beta2 –> v1 –> v2alpha1.
Each API version then provides a set of Resources. The apps/v1 group version for example provides Deployments and DaemonSets, whereas the rbac.authorization.k8s.io/v1 group offers resources like ClusterRoles.

The set of API groups and their versions and resources can be dynamically queried in a Kubernetes cluster in a process called "service discovery". This can be done using the standard Kubernetes CLI tool kubectl and running the command kubectl api-resources.

"Archived" is a totally arbitrary distinction made solely for the purpose of keeping the timeline to a consistent width. As new Kubernetes releases come out, not all screen sizes would be able to keep up, so I had to make a cut somewhere.

Use the "Show archived releases" switch to show all Kubernetes releases for which this site has gathered data.

The default view on kube-api.ninja will show a table of the 10 most recent Kubernetes releases (one per column). Older releases can be shown, but are only listed for historical purpose (if you have to administer a Kubernetes environment using an archived release, may the sun always be shining on you).

The columns marked green represented releases that are currently supported by the Kubernetes maintainers and will receive updates and security fixes.

Each row represents an API group and shows with a green bar in which Kubernetes releases the group is available. An empty cell means that the API is not available in that Kubernetes release.
The text in the API group cells shows the preferred version to use. Preferred is not necessarily the latest version, but the most mature (for example if both v1 and v2beta1 are available, v1 is preferred).

By clicking on an API group, the group can be expanded to show all individual API versions for that group. The bars now make use of multiple colors:

• A green bar means that the API version is available and the preferred version in that Kubernetes release.
• A yellow bar means that the API version is available, but not preferred.
• An empty cell means the API version is not available at all.

Just as you can expand an API group to show its versions, you can ultimately expand an API version to show the resources it offers. Note that during the lifetime of an API version, resources can be added and in unstable versions, resources can even be removed again.

Release columns marked green represent those that are currently supported by the Kubernetes maintainers. More information on the support policy can be found on the Kubernetes website.

For historical reasons, some Kubernetes APIs have names that are not fully-qualified (like apps). For these groups it is unlikely to ever change, but newly introduced API groups will follow a stricter naming scheme.

Cluster administrators can restrict the set of available APIs globally by reconfiguring the Kubernetes control plane (specifially the kube-apiserver). As a regular user, even with cluster-admin permissions, you have no influence over the availability of core APIs.

The documentation generator is based around Swagger 2.0 specs. Before Kubernetes 1.7, only Swagger 1.2 specs are available.

No!

Third party software in your cluster can extend the available APIs. For example Jetstack's cert-manager introduces its own API, cert-manager.io/v1, to manage TLS certificates. While third party APIs are not bound to Kubernetes releases, it is entirely possible that as part of your cluster upgrade, you would also need to upgrade cert-manager, which in itself might deprecate its v1 and instead use v2 now.

When planning a cluster upgrade, check all API versions in use in your cluster (for example using kubectl api-resources). For core APIs you can use this website to get a feeling for the impact, but each third party API needs to be checked invidually.

There are tools available to help you scan your cluster for resources that could become a problem when upgrading. This is a non-exhaustive alphabetical list:

• kube-no-trouble
• Pluto
• Popeye

There are two aspects that are considered notable:

1. An API resource is removed. This is simply a breaking change and it means cluster contents must be upgraded to not use the removed resource before control plane upgrade is attempted.
2. A more mature API version becomes available, but only if this new version offers at least one of the existing API resources. For example if apps.v1alpha1/DaemonSet was available in release 1.17 and 1.18 begins to offer apps.v1beta1/DaemonSet, then this is a notable change in 1.18. However if the new v1beta1 would not offer DaemonSets (yet), the new version is not a notable change, as it is not relevant when planning cluster upgrades.