kubernetes
/
website
mirror of https://github.com/kubernetes/website.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
website/content/en/docs/concepts/overview/kubernetes-api.md

231 lines
9.4 KiB
Markdown
Raw Blame History

---
reviewers:
- chenopis
title: The Kubernetes API
content_type: concept
weight: 30
description: >
The Kubernetes API lets you query and manipulate the state of objects in Kubernetes.
The core of Kubernetes' control plane is the API server and the HTTP API that it exposes. Users, the different parts of your cluster, and external components all communicate with one another through the API server.
card:
name: concepts
weight: 30
---
<!-- overview -->
The core of Kubernetes' {{< glossary_tooltip text="control plane" term_id="control-plane" >}}
is the {{< glossary_tooltip text="API server" term_id="kube-apiserver" >}}. The API server
exposes an HTTP API that lets end users, different parts of your cluster, and
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.
Consider using one of the [client libraries](/docs/reference/using-api/client-libraries/)
if you are writing an application using the Kubernetes API.
<!-- body -->
## OpenAPI specification {#api-specification}
Complete API details are documented using [OpenAPI](https://www.openapis.org/).
### OpenAPI V2
The Kubernetes API server serves an aggregated OpenAPI v2 spec via the
`/openapi/v2` endpoint. You can request the response format using
request headers as follows:
<table>
<caption style="display:none">Valid request header values for OpenAPI v2 queries</caption>
<thead>
<tr>
<th>Header</th>
<th style="min-width: 50%;">Possible values</th>
<th>Notes</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>Accept-Encoding</code></td>
<td><code>gzip</code></td>
<td><em>not supplying this header is also acceptable</em></td>
</tr>
<tr>
<td rowspan="3"><code>Accept</code></td>
<td><code>application/com.github.proto-openapi.spec.v2@v1.0+protobuf</code></td>
<td><em>mainly for intra-cluster use</em></td>
</tr>
<tr>
<td><code>application/json</code></td>
<td><em>default</em></td>
</tr>
<tr>
<td><code>*</code></td>
<td><em>serves </em><code>application/json</code></td>
</tr>
</tbody>
</table>
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://github.com/kubernetes/community/blob/master/contributors/design-proposals/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
{{< feature-state state="beta" for_k8s_version="v1.24" >}}
Kubernetes {{< param "version" >}} offers beta support for publishing its APIs as OpenAPI v3; this is a
beta feature that is enabled by default.
You can disable the beta feature by turning off the
[feature gate](/docs/reference/command-line-tools-reference/feature-gates/) named `OpenAPIV3`
for the kube-apiserver component.
A discovery endpoint `/openapi/v3` is provided to see a list of all
group/versions available. This endpoint only returns JSON. These group/versions
are provided in the following format:
```json
{
"paths": {
...
"api/v1": {
"serverRelativeURL": "/openapi/v3/api/v1?hash=CC0E9BFD992D8C59AEC98A1E2336F899E8318D3CF4C68944C3DEC640AF5AB52D864AC50DAA8D145B3494F75FA3CFF939FCBDDA431DAD3CA79738B297795818CF"
},
"apis/admissionregistration.k8s.io/v1": {
"serverRelativeURL": "/openapi/v3/apis/admissionregistration.k8s.io/v1?hash=E19CC93A116982CE5422FC42B590A8AFAD92CDE9AE4D59B5CAAD568F083AD07946E6CB5817531680BCE6E215C16973CD39003B0425F3477CFD854E89A9DB6597"
},
...
}
```
The relative URLs are pointing to immutable OpenAPI descriptions, in
order to improve client-side caching. The proper HTTP caching headers
are also set by the API server for that purpose (`Expires` to 1 year in
the future, and `Cache-Control` to `immutable`). When an obsolete URL is
used, the API server returns a redirect to the newest URL.
The Kubernetes API server publishes an OpenAPI v3 spec per Kubernetes
group version at the `/openapi/v3/apis/<group>/<version>?hash=<hash>`
endpoint.
Refer to the table below for accepted request headers.
<table>
<caption style="display:none">Valid request header values for OpenAPI v3 queries</caption>
<thead>
<tr>
<th>Header</th>
<th style="min-width: 50%;">Possible values</th>
<th>Notes</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>Accept-Encoding</code></td>
<td><code>gzip</code></td>
<td><em>not supplying this header is also acceptable</em></td>
</tr>
<tr>
<td rowspan="3"><code>Accept</code></td>
<td><code>application/com.github.proto-openapi.spec.v3@v1.0+protobuf</code></td>
<td><em>mainly for intra-cluster use</em></td>
</tr>
<tr>
<td><code>application/json</code></td>
<td><em>default</em></td>
</tr>
<tr>
<td><code>*</code></td>
<td><em>serves </em><code>application/json</code></td>
</tr>
</tbody>
</table>
## Persistence
Kubernetes stores the serialized state of objects by writing them into
{{< glossary_tooltip term_id="etcd" >}}.
## API groups and versioning
To make it easier to eliminate fields or restructure resource representations,
Kubernetes supports multiple API versions, each at a different API path, such
as `/api/v1` or `/apis/rbac.authorization.k8s.io/v1alpha1`.
Versioning is done at the API level rather than at the resource or field level
to ensure that the API presents a clear, consistent view of system resources
and behavior, and to enable controlling access to end-of-life and/or
experimental APIs.
To make it easier to evolve and to extend its API, Kubernetes implements
[API groups](/docs/reference/using-api/#api-groups) that can be
[enabled or disabled](/docs/reference/using-api/#enabling-or-disabling).
API resources are distinguished by their API group, resource type, namespace
(for namespaced resources), and name. The API server handles the conversion between
API versions transparently: all the different versions are actually representations
of the same persisted data. The API server may serve the same underlying data
through multiple API versions.
For example, suppose there are two API versions, `v1` and `v1beta1`, for the same
resource. If you originally created an object using the `v1beta1` version of its
API, you can later read, update, or delete that object
using either the `v1beta1` or the `v1` API version.
### API changes
Any system that is successful needs to grow and change as new use cases emerge or existing ones change.
Therefore, Kubernetes has designed the Kubernetes API to continuously change and grow.
The Kubernetes project aims to _not_ break compatibility with existing clients, and to maintain that
compatibility for a length of time so that other projects have an opportunity to adapt.
In general, new API resources and new resource fields can be added often and frequently.
Elimination of resources or fields requires following the
[API deprecation policy](/docs/reference/using-api/deprecation-policy/).
Kubernetes makes a strong commitment to maintain compatibility for official Kubernetes APIs
once they reach general availability (GA), typically at API version `v1`. Additionally,
Kubernetes keeps compatibility even for _beta_ API versions wherever feasible:
if you adopt a beta API you can continue to interact with your cluster using that API,
even after the feature goes stable.
{{< note >}}
Although Kubernetes also aims to maintain compatibility for _alpha_ APIs versions, in some
circumstances this is not possible. If you use any alpha API versions, check the release notes
for Kubernetes when upgrading your cluster, in case the API did change.
{{< /note >}}
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:
1. [Custom resources](/docs/concepts/extend-kubernetes/api-extension/custom-resources/)
let you declaratively define how the API server should provide your chosen resource API.
1. You can also extend the Kubernetes API by implementing an
[aggregation layer](/docs/concepts/extend-kubernetes/api-extension/apiserver-aggregation/).
## {{% heading "whatsnext" %}}
- Learn how to extend the Kubernetes API by adding your own
[CustomResourceDefinition](/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/).
- [Controlling Access To The Kubernetes API](/docs/concepts/security/controlling-access/) describes
how the cluster manages authentication and authorization for API access.
- Learn about API endpoints, resource types and samples by reading
[API Reference](/docs/reference/kubernetes-api/).
- Learn about what constitutes a compatible change, and how to change the API, from
[API changes](https://git.k8s.io/community/contributors/devel/sig-architecture/api_changes.md#readme).
Reference in New Issue View Git Blame Copy Permalink