Skip to content

Commit 33e5d85

Browse files
k8s-ci-robotk8s-ci-robot
authored
Merge pull request #43983 from Jefftree/kubernetes-api-improved-documentation
Add additional documentation around discovery and OpenAPI
2 parents 2f273d6 + 065ac71 commit 33e5d85

File tree

1 file changed

+141
-17
lines changed

1 file changed

+141
-17
lines changed

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

Lines changed: 141 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -22,21 +22,139 @@ 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 libraries](/docs/reference/using-api/client-libraries/)
30+
for those looking to
31+
write applications using the Kubernetes API.
32+
33+
Each Kubernetes cluster publishes the specification of the APIs that the cluster serves.
34+
There are two mechanisms that Kubernetes uses to publish these API specifications; both are useful
35+
to enable automatic interoperability. For example, the `kubectl` tool fetches and caches the API
36+
specification for enabling command-line completion and other features.
37+
The two supported mechanisms are as follows:
38+
39+
- [The Discovery API](#discovery-api) provides information about the Kubernetes APIs:
40+
API names, resources, versions, and supported operations. This is a Kubernetes
41+
specific term as it is a separate API from the Kubernetes OpenAPI.
42+
It is intended to be a brief summary of the available resources and it does not
43+
detail specific schema for the resources. For reference about resource schemas,
44+
please refer to the OpenAPI document.
45+
46+
- The [Kubernetes OpenAPI Document](#openapi-specification) provides (full)
47+
[OpenAPI v2.0 and 3.0 schemas](https://www.openapis.org/) for all Kubernetes API
48+
endpoints.
49+
The OpenAPI v3 is the preferred method for accessing OpenAPI as it
50+
provides
51+
a more comprehensive and accurate view of the API. It includes all the available
52+
API paths, as well as all resources consumed and produced for every operations
53+
on every endpoints. It also includes any extensibility components that a cluster supports.
54+
The data is a complete specification and is significantly larger than that from the
55+
Discovery API.
56+
57+
## Discovery API
58+
59+
Kubernetes publishes a list of all group versions and resources supported via
60+
the Discovery API. This includes the following for each resource:
61+
62+
- Name
63+
- Cluster or namespaced scope
64+
- Endpoint URL and supported verbs
65+
- Alternative names
66+
- Group, version, kind
67+
68+
The API is available both aggregated and unaggregated form. The aggregated
69+
discovery serves two endpoints while the unaggregated discovery serves a
70+
separate endpoint for each group version.
71+
72+
### Aggregated discovery
73+
74+
{{< feature-state state="beta" for_k8s_version="v1.27" >}}
3075

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.
76+
Kubernetes offers beta support for aggregated discovery, publishing
77+
all resources supported by a cluster through two endpoints (`/api` and
78+
`/apis`). Requesting this
79+
endpoint drastically reduces the number of requests sent to fetch the
80+
discovery data from the cluster. You can access the data by
81+
requesting the respective endpoints with an `Accept` header indicating
82+
the aggregated discovery resource:
83+
`Accept: application/json;v=v2beta1;g=apidiscovery.k8s.io;as=APIGroupDiscoveryList`.
84+
85+
Without indicating the resource type using the `Accept` header, the default
86+
response for the `/api` and `/apis` endpoint is an unaggregated discovery
87+
document.
88+
89+
The [discovery document](https://github.com/kubernetes/kubernetes/blob/release-v{{< skew currentVersion >}}/api/discovery/aggregated_v2beta1.json)
90+
for the built-in resources can be found in the Kubernetes GitHub repository.
91+
This Github document can be used as a reference of the base set of the available resources
92+
if a Kubernetes cluster is not available to query.
93+
94+
The endpoint also supports ETag and protobuf encoding.
95+
96+
### Unaggregated discovery
97+
98+
Without discovery aggregation, discovery is published in levels, with the root
99+
endpoints publishing discovery information for downstream documents.
100+
101+
A list of all group versions supported by a cluster is published at
102+
the `/api` and `/apis` endpoints. Example:
103+
104+
```
105+
{
106+
"kind": "APIGroupList",
107+
"apiVersion": "v1",
108+
"groups": [
109+
{
110+
"name": "apiregistration.k8s.io",
111+
"versions": [
112+
{
113+
"groupVersion": "apiregistration.k8s.io/v1",
114+
"version": "v1"
115+
}
116+
],
117+
"preferredVersion": {
118+
"groupVersion": "apiregistration.k8s.io/v1",
119+
"version": "v1"
120+
}
121+
},
122+
{
123+
"name": "apps",
124+
"versions": [
125+
{
126+
"groupVersion": "apps/v1",
127+
"version": "v1"
128+
}
129+
],
130+
"preferredVersion": {
131+
"groupVersion": "apps/v1",
132+
"version": "v1"
133+
}
134+
},
135+
...
136+
}
137+
```
138+
139+
Additional requests are needed to obtain the discovery document for each group version at
140+
`/apis/<group>/<version>` (for example:
141+
`/apis/rbac.authorization.k8s.io/v1alpha1`), which advertises the list of
142+
resources served under a particular group version. These endpoints are used by
143+
kubectl to fetch the list of resources supported by a cluster.
33144

34145
<!-- body -->
35146

36-
## OpenAPI specification {#api-specification}
147+
<a id="#api-specification" />
37148

38-
Complete API details are documented using [OpenAPI](https://www.openapis.org/).
149+
## OpenAPI interface definition
39150

151+
For details about the OpenAPI specifications, see the [OpenAPI documentation](https://www.openapis.org/).
152+
153+
Kubernetes serves both OpenAPI v2.0 and OpenAPI v3.0. OpenAPI v3 is the
154+
preferred method of accessing the OpenAPI because it offers a more comprehensive
155+
(lossless) representation of Kubernetes resources. Due to limitations of OpenAPI
156+
version 2, certain fields are dropped from the published OpenAPI including but not
157+
limited to `default`, `nullable`, `oneOf`.
40158
### OpenAPI V2
41159

42160
The Kubernetes API server serves an aggregated OpenAPI v2 spec via the
@@ -74,11 +192,6 @@ request headers as follows:
74192
</tbody>
75193
</table>
76194

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.
82195

83196
### OpenAPI V3
84197

@@ -149,7 +262,20 @@ Refer to the table below for accepted request headers.
149262
</tbody>
150263
</table>
151264

152-
A Golang implementation to fetch the OpenAPI V3 is provided in the package `k8s.io/client-go/openapi3`.
265+
A Golang implementation to fetch the OpenAPI V3 is provided in the package
266+
[`k8s.io/client-go/openapi3`](https://pkg.go.dev/k8s.io/client-go/openapi3).
267+
268+
Kubernetes {{< skew currentVersion >}} publishes
269+
OpenAPI v2.0 and v3.0; there are no plans to support 3.1 in the near future.
270+
271+
### Protobuf serialization
272+
273+
Kubernetes implements an alternative Protobuf based serialization format that
274+
is primarily intended for intra-cluster communication. For more information
275+
about this format, see the [Kubernetes Protobuf serialization](https://git.k8s.io/design-proposals-archive/api-machinery/protobuf.md)
276+
design proposal and the
277+
Interface Definition Language (IDL) files for each schema located in the Go
278+
packages that define the API objects.
153279

154280
## Persistence
155281

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

241-
242-
243367
## API Extension
244368

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

0 commit comments

Comments
 (0)