Skip to content

Commit 622466f

Browse files
JefftreeJefftree
committed
Add additional information around discovery and OpenAPI
1 parent 67828d5 commit 622466f

File tree

1 file changed

+131
-17
lines changed

1 file changed

+131
-17
lines changed

‎content/en/docs/concepts/overview/kubernetes-api.md

Lines changed: 131 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -22,21 +22,131 @@ external components communicate with one another.
2222
The Kubernetes API lets you query and manipulate the state of API objects in Kubernetes
2323
(for example: Pods, Namespaces, ConfigMaps, and Events).
2424

25-
Most operations can be performed through the
26-
[kubectl](/docs/reference/kubectl/) command-line interface or other
27-
command-line tools, such as
28-
[kubeadm](/docs/reference/setup-tools/kubeadm/), which in turn use the
29-
API. However, you can also access the API directly using REST calls.
25+
Most operations can be performed through the [kubectl](/docs/reference/kubectl/)
26+
command-line interface or other command-line tools, such as
27+
[kubeadm](/docs/reference/setup-tools/kubeadm/), which in turn use the API.
28+
However, you can also access the API directly using REST calls. Kubernetes
29+
provides a set of [client
30+
libraries](/docs/reference/using-api/client-libraries/) for those looking to
31+
write applications using the Kubernetes API.
32+
33+
Each Kubernetes offers publishes a machine-readable description of the APIs that the cluster serves.
34+
There are two mechanisms that Kubernetes uses to publish these API descriptions; each is useful
35+
to enable automatic interoperability. For example, the `kubectl` tool fetches and caches the API
36+
description and uses this to enable command-line completion and other features.
37+
Here is some more detail about each of those two mechanisms:
38+
39+
[The Discovery API](#discovery-api) provides information about the Kubernetes APIs: API names,
40+
resources, versions, and supported operations. This is a Kubernetes specific term as it is a separate API from the Kubernetes OpenAPI.
41+
It is intended to be a small document providing a summary of available resources
42+
and does not detail specific schema for the resources. For reference around schemas
43+
for resources, please refer to the OpenAPI document.
44+
45+
The [Kubernetes OpenAPI Document]{#openapi-specification} provides (full) [OpenAPI v2.0 and 3.0 schemas](https://www.openapis.org/) for all Kubernetes API
46+
endpoints. OpenAPI v3 is the preferred method for accessing OpenAPI as it
47+
provides a more comprehensive and accurate view of the API. It includes all
48+
available API paths, as well as all resources consumed and produced for every
49+
operation on every endpoint. This also includes any extensibility components
50+
that a cluster supports. This document a complete document and is significantly larger than Discovery. The Discovery API is a
51+
lightweight alternative that provides a subset of information in the
52+
Kubernetes OpenAPI document.
53+
54+
## Discovery API
55+
56+
Kubernetes publishes a list of all group versions and resources supported via
57+
the Discovery API. This includes the following for each resource:
58+
59+
- Name
60+
- Cluster or Namespace scope
61+
- Endpoint URL and supported verbs
62+
- Alternative names
63+
- Group, version, kind
64+
65+
The API is available both aggregated and unaggregated form. The aggregated
66+
discovery serves two endpoints while the unaggregated discovery serves a
67+
separate endpoint for each group version.
3068

31-
Consider using one of the [client libraries](/docs/reference/using-api/client-libraries/)
32-
if you are writing an application using the Kubernetes API.
69+
### Aggregated Discovery
70+
71+
{{< feature-state state="beta" for_k8s_version="v1.27" >}}
72+
73+
Kubernetes offers beta support for aggregated discovery, publishing
74+
all resources supported by a cluster through two endpoints (`/api` and
75+
`/apis`). Requesting this
76+
endpoint drastically reduces the number of requests sent to fetch the
77+
discovery for the average Kubernetes cluster. This may be accessed by
78+
requesting the respective endpoints with an Accept header indicating
79+
the aggregated discovery resource:
80+
`Accept: application/json;v=v2beta1;g=apidiscovery.k8s.io;as=APIGroupDiscoveryList`.
81+
82+
Without the Accept header resource type explicitly indicated, the default
83+
response for the `/api` and `/apis` endpoint is an unaggregated discovery
84+
document.
85+
86+
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.
87+
88+
The endpoint also supports ETag and protobuf encoding.
89+
90+
### Unaggregated discovery
91+
92+
Without discovery aggregation, discovery is published in levels, with the root
93+
endpoints publishing discovery information for downstream documents.
94+
95+
A list of all group versions supported by a cluster is published at
96+
the `/api` and `/apis` endpoints. Example:
97+
98+
```
99+
{
100+
"kind": "APIGroupList",
101+
"apiVersion": "v1",
102+
"groups": [
103+
{
104+
"name": "apiregistration.k8s.io",
105+
"versions": [
106+
{
107+
"groupVersion": "apiregistration.k8s.io/v1",
108+
"version": "v1"
109+
}
110+
],
111+
"preferredVersion": {
112+
"groupVersion": "apiregistration.k8s.io/v1",
113+
"version": "v1"
114+
}
115+
},
116+
{
117+
"name": "apps",
118+
"versions": [
119+
{
120+
"groupVersion": "apps/v1",
121+
"version": "v1"
122+
}
123+
],
124+
"preferredVersion": {
125+
"groupVersion": "apps/v1",
126+
"version": "v1"
127+
}
128+
},
129+
...
130+
}
131+
```
132+
133+
Additional requests are needed to obtain the discovery document for each group version at
134+
`/apis/<group>/<version>` (for example:
135+
`/apis/rbac.authorization.k8s.io/v1alpha1`), which advertises the list of
136+
resources served under a particular group version. These endpoints are used by
137+
kubectl to fetch the list of resources supported by a cluster.
33138

34139
<!-- body -->
35140

36-
## OpenAPI specification {#api-specification}
141+
## OpenAPI Specification
37142

38-
Complete API details are documented using [OpenAPI](https://www.openapis.org/).
143+
For details about the OpenAPI specifications, see the [OpenAPI documentation](https://www.openapis.org/).
39144

145+
Kubernetes serves both OpenAPI v2.0 and OpenAPI v3.0. OpenAPI v3 is the
146+
preferred method of accessing the OpenAPI because it offers a more comprehensive
147+
(lossless) representation of Kubernetes resources. Due to limitations of OpenAPI
148+
version 2, certain fields are dropped from the published OpenAPI including but not
149+
limited to `default`, `nullable`, `oneOf`.
40150
### OpenAPI V2
41151

42152
The Kubernetes API server serves an aggregated OpenAPI v2 spec via the
@@ -74,11 +184,6 @@ request headers as follows:
74184
</tbody>
75185
</table>
76186

77-
Kubernetes implements an alternative Protobuf based serialization format that
78-
is primarily intended for intra-cluster communication. For more information
79-
about this format, see the [Kubernetes Protobuf serialization](https://git.k8s.io/design-proposals-archive/api-machinery/protobuf.md) design proposal and the
80-
Interface Definition Language (IDL) files for each schema located in the Go
81-
packages that define the API objects.
82187

83188
### OpenAPI V3
84189

@@ -149,7 +254,18 @@ Refer to the table below for accepted request headers.
149254
</tbody>
150255
</table>
151256

152-
A Golang implementation to fetch the OpenAPI V3 is provided in the package `k8s.io/client-go/openapi3`.
257+
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).
258+
259+
Kubernetes {{< skew currentVersion >}} publishes
260+
OpenAPI v2.0 and v3.0; there are no plans to support 3.1 in the near future.
261+
262+
### Protobuf serialization
263+
264+
Kubernetes implements an alternative Protobuf based serialization format that
265+
is primarily intended for intra-cluster communication. For more information
266+
about this format, see the [Kubernetes Protobuf serialization](https://git.k8s.io/design-proposals-archive/api-machinery/protobuf.md) design proposal and the
267+
Interface Definition Language (IDL) files for each schema located in the Go
268+
packages that define the API objects.
153269

154270
## Persistence
155271

@@ -238,8 +354,6 @@ ways that require deleting all existing alpha objects prior to upgrade.
238354
Refer to [API versions reference](/docs/reference/using-api/#api-versioning)
239355
for more details on the API version level definitions.
240356

241-
242-
243357
## API Extension
244358

245359
The Kubernetes API can be extended in one of two ways:

0 commit comments

Comments
 (0)