From 622466f5cf5ba712d261fd2d874404b1d2840e42 Mon Sep 17 00:00:00 2001 From: Jefftree Date: Fri, 17 Nov 2023 13:18:45 -0500 Subject: [PATCH] Add additional information around discovery and OpenAPI --- .../docs/concepts/overview/kubernetes-api.md | 148 ++++++++++++++++-- 1 file changed, 131 insertions(+), 17 deletions(-) diff --git a/content/en/docs/concepts/overview/kubernetes-api.md b/content/en/docs/concepts/overview/kubernetes-api.md index f7e6da3d86..a7447b1c37 100644 --- a/content/en/docs/concepts/overview/kubernetes-api.md +++ b/content/en/docs/concepts/overview/kubernetes-api.md @@ -22,21 +22,131 @@ external components communicate with one another. The Kubernetes API lets you query and manipulate the state of API objects in Kubernetes (for example: Pods, Namespaces, ConfigMaps, and Events). -Most operations can be performed through the -[kubectl](/docs/reference/kubectl/) command-line interface or other -command-line tools, such as -[kubeadm](/docs/reference/setup-tools/kubeadm/), which in turn use the -API. However, you can also access the API directly using REST calls. +Most operations can be performed through the [kubectl](/docs/reference/kubectl/) +command-line interface or other command-line tools, such as +[kubeadm](/docs/reference/setup-tools/kubeadm/), which in turn use the API. +However, you can also access the API directly using REST calls. Kubernetes +provides a set of [client +libraries](/docs/reference/using-api/client-libraries/) for those looking to +write applications using the Kubernetes API. -Consider using one of the [client libraries](/docs/reference/using-api/client-libraries/) -if you are writing an application using the Kubernetes API. +Each Kubernetes offers publishes a machine-readable description of the APIs that the cluster serves. +There are two mechanisms that Kubernetes uses to publish these API descriptions; each is useful +to enable automatic interoperability. For example, the `kubectl` tool fetches and caches the API +description and uses this to enable command-line completion and other features. +Here is some more detail about each of those two mechanisms: + +[The Discovery API](#discovery-api) provides information about the Kubernetes APIs: API names, +resources, versions, and supported operations. This is a Kubernetes specific term as it is a separate API from the Kubernetes OpenAPI. +It is intended to be a small document providing a summary of available resources +and does not detail specific schema for the resources. For reference around schemas +for resources, please refer to the OpenAPI document. + +The [Kubernetes OpenAPI Document]{#openapi-specification} provides (full) [OpenAPI v2.0 and 3.0 schemas](https://www.openapis.org/) for all Kubernetes API +endpoints. OpenAPI v3 is the preferred method for accessing OpenAPI as it +provides a more comprehensive and accurate view of the API. It includes all +available API paths, as well as all resources consumed and produced for every +operation on every endpoint. This also includes any extensibility components +that a cluster supports. This document a complete document and is significantly larger than Discovery. The Discovery API is a +lightweight alternative that provides a subset of information in the +Kubernetes OpenAPI document. + +## Discovery API + +Kubernetes publishes a list of all group versions and resources supported via +the Discovery API. This includes the following for each resource: + +- Name +- Cluster or Namespace scope +- Endpoint URL and supported verbs +- Alternative names +- Group, version, kind + +The API is available both aggregated and unaggregated form. The aggregated +discovery serves two endpoints while the unaggregated discovery serves a +separate endpoint for each group version. + +### Aggregated Discovery + +{{< feature-state state="beta" for_k8s_version="v1.27" >}} + +Kubernetes offers beta support for aggregated discovery, publishing +all resources supported by a cluster through two endpoints (`/api` and +`/apis`). Requesting this +endpoint drastically reduces the number of requests sent to fetch the +discovery for the average Kubernetes cluster. This may be accessed by +requesting the respective endpoints with an Accept header indicating +the aggregated discovery resource: +`Accept: application/json;v=v2beta1;g=apidiscovery.k8s.io;as=APIGroupDiscoveryList`. + +Without the Accept header resource type explicitly indicated, the default +response for the `/api` and `/apis` endpoint is an unaggregated discovery +document. + +The [discovery document](https://github.com/kubernetes/kubernetes/blob/release-v{{< skew currentVersion >}}/api/discovery/aggregated_v2beta1.json) serving built-in resources is found in the Kubernetes Github repository. This Github document can be used as a reference of the base set of available resources if a Kubernetes cluster is not available to query. + +The endpoint also supports ETag and protobuf encoding. + +### Unaggregated discovery + +Without discovery aggregation, discovery is published in levels, with the root +endpoints publishing discovery information for downstream documents. + +A list of all group versions supported by a cluster is published at +the `/api` and `/apis` endpoints. Example: + +``` +{ + "kind": "APIGroupList", + "apiVersion": "v1", + "groups": [ + { + "name": "apiregistration.k8s.io", + "versions": [ + { + "groupVersion": "apiregistration.k8s.io/v1", + "version": "v1" + } + ], + "preferredVersion": { + "groupVersion": "apiregistration.k8s.io/v1", + "version": "v1" + } + }, + { + "name": "apps", + "versions": [ + { + "groupVersion": "apps/v1", + "version": "v1" + } + ], + "preferredVersion": { + "groupVersion": "apps/v1", + "version": "v1" + } + }, + ... +} +``` + +Additional requests are needed to obtain the discovery document for each group version at +`/apis//` (for example: +`/apis/rbac.authorization.k8s.io/v1alpha1`), which advertises the list of +resources served under a particular group version. These endpoints are used by +kubectl to fetch the list of resources supported by a cluster. -## OpenAPI specification {#api-specification} +## OpenAPI Specification -Complete API details are documented using [OpenAPI](https://www.openapis.org/). +For details about the OpenAPI specifications, see the [OpenAPI documentation](https://www.openapis.org/). +Kubernetes serves both OpenAPI v2.0 and OpenAPI v3.0. OpenAPI v3 is the +preferred method of accessing the OpenAPI because it offers a more comprehensive +(lossless) representation of Kubernetes resources. Due to limitations of OpenAPI +version 2, certain fields are dropped from the published OpenAPI including but not +limited to `default`, `nullable`, `oneOf`. ### OpenAPI V2 The Kubernetes API server serves an aggregated OpenAPI v2 spec via the @@ -74,11 +184,6 @@ request headers as follows: -Kubernetes implements an alternative Protobuf based serialization format that -is primarily intended for intra-cluster communication. For more information -about this format, see the [Kubernetes Protobuf serialization](https://git.k8s.io/design-proposals-archive/api-machinery/protobuf.md) design proposal and the -Interface Definition Language (IDL) files for each schema located in the Go -packages that define the API objects. ### OpenAPI V3 @@ -149,7 +254,18 @@ Refer to the table below for accepted request headers. -A Golang implementation to fetch the OpenAPI V3 is provided in the package `k8s.io/client-go/openapi3`. +A Golang implementation to fetch the OpenAPI V3 is provided in the package [`k8s.io/client-go/openapi3`](https://pkg.go.dev/k8s.io/client-go/openapi3). + + Kubernetes {{< skew currentVersion >}} publishes +OpenAPI v2.0 and v3.0; there are no plans to support 3.1 in the near future. + +### Protobuf serialization + +Kubernetes implements an alternative Protobuf based serialization format that +is primarily intended for intra-cluster communication. For more information +about this format, see the [Kubernetes Protobuf serialization](https://git.k8s.io/design-proposals-archive/api-machinery/protobuf.md) design proposal and the +Interface Definition Language (IDL) files for each schema located in the Go +packages that define the API objects. ## Persistence @@ -238,8 +354,6 @@ ways that require deleting all existing alpha objects prior to upgrade. Refer to [API versions reference](/docs/reference/using-api/#api-versioning) for more details on the API version level definitions. - - ## API Extension The Kubernetes API can be extended in one of two ways: