Merge pull request #23866 from tengqm/refactor-api-concept
Remove duplicated content in concepts and reference
This commit is contained in:
Kubernetes Prow Robot
@@ -16,30 +16,23 @@ card:
|
|||||||
|
|
||||||
The core of Kubernetes' {{< glossary_tooltip text="control plane" term_id="control-plane" >}}
|
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
|
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
|
exposes an HTTP API that lets end users, different parts of your cluster, and
|
||||||
communicate with one another.
|
external components communicate with one another.
|
||||||
|
|
||||||
The Kubernetes API lets you query and manipulate the state of objects in the Kubernetes API
|
The Kubernetes API lets you query and manipulate the state of objects in the Kubernetes API
|
||||||
(for example: Pods, Namespaces, ConfigMaps, and Events).
|
(for example: Pods, Namespaces, ConfigMaps, and Events).
|
||||||
|
|
||||||
API endpoints, resource types and samples are described in the [API Reference](/docs/reference/kubernetes-api/).
|
Most operations can be performed through the
|
||||||
|
[kubectl](/docs/reference/kubectl/overview/) command-line interface or other
|
||||||
|
command-line tools, such as
|
||||||
|
[kubeadm](/docs/reference/setup-tools/kubeadm/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 -->
|
<!-- body -->
|
||||||
|
|
||||||
## API changes
|
|
||||||
|
|
||||||
Any system that is successful needs to grow and change as new use cases emerge or existing ones change.
|
|
||||||
Therefore, Kubernetes has design features to allow 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/).
|
|
||||||
|
|
||||||
What constitutes a compatible change, and how to change the API, are detailed in
|
|
||||||
[API changes](https://git.k8s.io/community/contributors/devel/sig-architecture/api_changes.md#readme).
|
|
||||||
|
|
||||||
## OpenAPI specification {#api-specification}
|
## OpenAPI specification {#api-specification}
|
||||||
|
|
||||||
Complete API details are documented using [OpenAPI](https://www.openapis.org/).
|
Complete API details are documented using [OpenAPI](https://www.openapis.org/).
|
||||||
@@ -78,95 +71,58 @@ You can request the response format using request headers as follows:
|
|||||||
<caption>Valid request header values for OpenAPI v2 queries</caption>
|
<caption>Valid request header values for OpenAPI v2 queries</caption>
|
||||||
</table>
|
</table>
|
||||||
|
|
||||||
Kubernetes implements an alternative Protobuf based serialization format for the API that is primarily intended for intra-cluster communication, documented in the [design proposal](https://github.com/kubernetes/community/blob/master/contributors/design-proposals/api-machinery/protobuf.md) and the IDL files for each schema are located in the Go packages that define the API objects.
|
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.
|
||||||
|
|
||||||
## API versioning
|
## API changes
|
||||||
|
|
||||||
To make it easier to eliminate fields or restructure resource representations, Kubernetes supports
|
Any system that is successful needs to grow and change as new use cases emerge or existing ones change.
|
||||||
multiple API versions, each at a different API path, such as `/api/v1` or
|
Therefore, Kubernetes has designed its features to allow the Kubernetes API to continuously change and grow.
|
||||||
`/apis/rbac.authorization.k8s.io/v1alpha1`.
|
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.
|
||||||
|
|
||||||
Versioning is done at the API level rather than at the resource or field level to ensure that the
|
In general, new API resources and new resource fields can be added often and frequently.
|
||||||
API presents a clear, consistent view of system resources and behavior, and to enable controlling
|
Elimination of resources or fields requires following the
|
||||||
access to end-of-life and/or experimental APIs.
|
[API deprecation policy](/docs/reference/using-api/deprecation-policy/).
|
||||||
|
|
||||||
The JSON and Protobuf serialization schemas follow the same guidelines for schema changes - all descriptions below cover both formats.
|
What constitutes a compatible change, and how to change the API, are detailed in
|
||||||
|
[API changes](https://git.k8s.io/community/contributors/devel/sig-architecture/api_changes.md#readme).
|
||||||
|
|
||||||
Note that API versioning and Software versioning are only indirectly related. The
|
## API groups and versioning
|
||||||
[Kubernetes Release Versioning](https://git.k8s.io/community/contributors/design-proposals/release/versioning.md)
|
|
||||||
proposal describes the relationship between API versioning and software versioning.
|
|
||||||
|
|
||||||
Different API versions imply different levels of stability and support. The criteria for each level are described
|
To make it easier to eliminate fields or restructure resource representations,
|
||||||
in more detail in the
|
Kubernetes supports multiple API versions, each at a different API path, such
|
||||||
[API Changes](https://git.k8s.io/community/contributors/devel/sig-architecture/api_changes.md#alpha-beta-and-stable-versions)
|
as `/api/v1` or `/apis/rbac.authorization.k8s.io/v1alpha1`.
|
||||||
documentation. They are summarized here:
|
|
||||||
|
|
||||||
- Alpha level:
|
Versioning is done at the API level rather than at the resource or field level
|
||||||
- The version names contain `alpha` (e.g. `v1alpha1`).
|
to ensure that the API presents a clear, consistent view of system resources
|
||||||
- May be buggy. Enabling the feature may expose bugs. Disabled by default.
|
and behavior, and to enable controlling access to end-of-life and/or
|
||||||
- Support for feature may be dropped at any time without notice.
|
experimental APIs.
|
||||||
- The API may change in incompatible ways in a later software release without notice.
|
|
||||||
- Recommended for use only in short-lived testing clusters, due to increased risk of bugs and lack of long-term support.
|
|
||||||
- Beta level:
|
|
||||||
- The version names contain `beta` (e.g. `v2beta3`).
|
|
||||||
- Code is well tested. Enabling the feature is considered safe. Enabled by default.
|
|
||||||
- Support for the overall feature will not be dropped, though details may change.
|
|
||||||
- The schema and/or semantics of objects may change in incompatible ways in a subsequent beta or stable release. When this happens,
|
|
||||||
we will provide instructions for migrating to the next version. This may require deleting, editing, and re-creating
|
|
||||||
API objects. The editing process may require some thought. This may require downtime for applications that rely on the feature.
|
|
||||||
- Recommended for only non-business-critical uses because of potential for incompatible changes in subsequent releases. If you have
|
|
||||||
multiple clusters which can be upgraded independently, you may be able to relax this restriction.
|
|
||||||
- **Please do try our beta features and give feedback on them! Once they exit beta, it may not be practical for us to make more changes.**
|
|
||||||
- Stable level:
|
|
||||||
- The version name is `vX` where `X` is an integer.
|
|
||||||
- Stable versions of features will appear in released software for many subsequent versions.
|
|
||||||
|
|
||||||
## API groups
|
Refer to [API versions reference](/docs/reference/using-api/api-overview/#api-versioning)
|
||||||
|
for more details on the API version level definitions.
|
||||||
|
|
||||||
To make it easier to extend its API, Kubernetes implements [*API groups*](https://git.k8s.io/community/contributors/design-proposals/api-machinery/api-group.md).
|
To make it easier to evolve and to extend its API, Kubernetes implements
|
||||||
The API group is specified in a REST path and in the `apiVersion` field of a serialized object.
|
[API groups](/docs/reference/using-api/api-overview/#api-groups) that can be
|
||||||
|
[enabled or disabled](/docs/reference/using-api/api-overview/#enabling-or-disabling).
|
||||||
|
|
||||||
There are several API groups in a cluster:
|
## API Extension
|
||||||
|
|
||||||
1. The *core* group, also referred to as the *legacy* group, is at the REST path `/api/v1` and uses `apiVersion: v1`.
|
The Kubernetes API can be extended in one of two ways:
|
||||||
|
|
||||||
1. *Named* groups are at REST path `/apis/$GROUP_NAME/$VERSION`, and use `apiVersion: $GROUP_NAME/$VERSION`
|
|
||||||
(e.g. `apiVersion: batch/v1`). The Kubernetes [API reference](/docs/reference/kubernetes-api/) has a
|
|
||||||
full list of available API groups.
|
|
||||||
|
|
||||||
There are two paths to extending the API with [custom resources](/docs/concepts/extend-kubernetes/api-extension/custom-resources/):
|
|
||||||
|
|
||||||
1. [CustomResourceDefinition](/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/)
|
|
||||||
lets you declaratively define how the API server should provide your chosen resource API.
|
|
||||||
1. You can also [implement your own extension API server](/docs/tasks/extend-kubernetes/setup-extension-api-server/)
|
|
||||||
and use the [aggregator](/docs/tasks/extend-kubernetes/configure-aggregation-layer/)
|
|
||||||
to make it seamless for clients.
|
|
||||||
|
|
||||||
## Enabling or disabling API groups
|
|
||||||
|
|
||||||
Certain resources and API groups are enabled by default. They can be enabled or disabled by setting `--runtime-config`
|
|
||||||
as a command line option to the kube-apiserver.
|
|
||||||
|
|
||||||
`--runtime-config` accepts comma separated values. For example: to disable batch/v1, set
|
|
||||||
`--runtime-config=batch/v1=false`; to enable batch/v2alpha1, set `--runtime-config=batch/v2alpha1`.
|
|
||||||
The flag accepts comma separated set of key=value pairs describing runtime configuration of the API server.
|
|
||||||
|
|
||||||
{{< note >}}Enabling or disabling groups or resources requires restarting the kube-apiserver and the
|
|
||||||
kube-controller-manager to pick up the `--runtime-config` changes.{{< /note >}}
|
|
||||||
|
|
||||||
## Persistence
|
|
||||||
|
|
||||||
Kubernetes stores its serialized state in terms of the API resources by writing them into
|
|
||||||
{{< glossary_tooltip term_id="etcd" >}}.
|
|
||||||
|
|
||||||
|
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" %}}
|
## {{% heading "whatsnext" %}}
|
||||||
|
|
||||||
[Controlling API Access](/docs/reference/access-authn-authz/controlling-access/) describes
|
- Learn how to extend the Kubernetes API by adding your own
|
||||||
how the cluster manages authentication and authorization for API access.
|
[CustomResourceDefinition](/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/).
|
||||||
|
- [Controlling API Access](/docs/reference/access-authn-authz/controlling-access/) describes
|
||||||
Overall API conventions are described in the
|
how the cluster manages authentication and authorization for API access.
|
||||||
[API conventions](https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#api-conventions)
|
- Learn about API endpoints, resource types and samples by reading
|
||||||
document.
|
[API Reference](/docs/reference/kubernetes-api/).
|
||||||
|
|
||||||
API endpoints, resource types and samples are described in the [API Reference](/docs/reference/kubernetes-api/).
|
|
||||||
|
|||||||
@@ -18,62 +18,55 @@ This page provides an overview of the Kubernetes API.
|
|||||||
|
|
||||||
<!-- body -->
|
<!-- body -->
|
||||||
|
|
||||||
The REST API is the fundamental fabric of Kubernetes. All operations and communications between components
|
The REST API is the fundamental fabric of Kubernetes. All operations and
|
||||||
and external user commands are REST API calls that the API Server handles. Consequently, everything in the Kubernetes
|
communications between components, and external user commands are REST API
|
||||||
|
calls that the API Server handles. Consequently, everything in the Kubernetes
|
||||||
platform is treated as an API object and has a corresponding entry in the
|
platform is treated as an API object and has a corresponding entry in the
|
||||||
[API](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/).
|
[API](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/).
|
||||||
|
|
||||||
Most operations can be performed through the
|
|
||||||
[kubectl](/docs/reference/kubectl/overview/) command-line interface or other
|
|
||||||
command-line tools, such as [kubeadm](/docs/reference/setup-tools/kubeadm/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.
|
|
||||||
|
|
||||||
## API versioning
|
## API versioning
|
||||||
|
|
||||||
To eliminate fields or restructure resource representations, Kubernetes supports
|
The JSON and Protobuf serialization schemas follow the same guidelines for
|
||||||
multiple API versions, each at a different API path. For example: `/api/v1` or
|
schema changes. The following descriptions cover both formats.
|
||||||
`/apis/rbac.authorization.k8s.io/v1alpha1`.
|
|
||||||
|
|
||||||
The version is set at the API level rather than at the resource or field level to:
|
The API versioning and software versioning are indirectly related.
|
||||||
|
The [API and release versioning proposal](https://git.k8s.io/community/contributors/design-proposals/release/versioning.md)
|
||||||
|
describes the relationship between API versioning and software versioning.
|
||||||
|
|
||||||
- Ensure that the API presents a clear and consistent view of system resources and behavior.
|
Different API versions indicate different levels of stability and support. You
|
||||||
- Enable control access to deprecated or experimental APIs.
|
can find more information about the criteria for each level in the
|
||||||
|
[API Changes documentation](https://git.k8s.io/community/contributors/devel/sig-architecture/api_changes.md#alpha-beta-and-stable-versions).
|
||||||
The JSON and Protobuf serialization schemas follow the same guidelines for schema changes. The following descriptions cover both formats.
|
|
||||||
|
|
||||||
{{< note >}}
|
|
||||||
The API versioning and software versioning are indirectly related. The [API and release
|
|
||||||
versioning proposal](https://git.k8s.io/community/contributors/design-proposals/release/versioning.md) describes the relationship between API versioning and software versioning.
|
|
||||||
{{< /note >}}
|
|
||||||
|
|
||||||
Different API versions indicate different levels of stability and support. You can find more information about the criteria for each level in the [API Changes documentation](https://git.k8s.io/community/contributors/devel/sig-architecture/api_changes.md#alpha-beta-and-stable-versions).
|
|
||||||
|
|
||||||
Here's a summary of each level:
|
Here's a summary of each level:
|
||||||
|
|
||||||
- Alpha:
|
- Alpha:
|
||||||
- The version names contain `alpha` (for example, `v1alpha1`).
|
- The version names contain `alpha` (for example, `v1alpha1`).
|
||||||
- The software may contain bugs. Enabling a feature may expose bugs. A feature may be disabled by default.
|
- The software may contain bugs. Enabling a feature may expose bugs. A
|
||||||
|
feature may be disabled by default.
|
||||||
- The support for a feature may be dropped at any time without notice.
|
- The support for a feature may be dropped at any time without notice.
|
||||||
- The API may change in incompatible ways in a later software release without notice.
|
- The API may change in incompatible ways in a later software release without notice.
|
||||||
- The software is recommended for use only in short-lived testing clusters due to increased risk of bugs
|
- The software is recommended for use only in short-lived testing clusters,
|
||||||
and lack of long-term support.
|
due to increased risk of bugs and lack of long-term support.
|
||||||
|
|
||||||
- Beta:
|
- Beta:
|
||||||
- The version names contain `beta` (for example, `v2beta3`).
|
- The version names contain `beta` (for example, `v2beta3`).
|
||||||
- The software is well tested. Enabling a feature is considered safe. Features are enabled by default.
|
- The software is well tested. Enabling a feature is considered safe.
|
||||||
|
Features are enabled by default.
|
||||||
- The support for a feature will not be dropped, though the details may change.
|
- The support for a feature will not be dropped, though the details may change.
|
||||||
- The schema or semantics of objects may change in incompatible ways in a subsequent beta or stable release.
|
|
||||||
When this happens, migration instructions are provided. Schema changes may require deleting, editing,
|
- The schema and/or semantics of objects may change in incompatible ways in
|
||||||
or recreating API objects. The editing process may not be straightforward. Migration may require
|
a subsequent beta or stable release. When this happens, migration
|
||||||
downtime for applications that rely on the feature.
|
instructions are provided. Schema changes may require deleting, editing, and
|
||||||
- The software is not recommended for production uses. Subsequent releases may introduce
|
re-creating API objects. The editing process may not be straightforward.
|
||||||
incompatible changes. If you have multiple clusters which can be upgraded independently,
|
The migration may require downtime for applications that rely on the feature.
|
||||||
you may be able to relax this restriction.
|
- The software is not recommended for production uses. Subsequent releases
|
||||||
- Try the beta features and provide feedback. After the features exit beta, it may not be practical
|
may introduce incompatible changes. If you have multiple clusters which
|
||||||
to make more changes.
|
can be upgraded independently, you may be able to relax this restriction.
|
||||||
|
|
||||||
|
{{< note >}}
|
||||||
|
Try the beta features and provide feedback. After the features exit beta, it
|
||||||
|
may not be practical to make more changes.
|
||||||
|
{{< /note >}}
|
||||||
|
|
||||||
- Stable:
|
- Stable:
|
||||||
- The version name is `vX` where `X` is an integer.
|
- The version name is `vX` where `X` is an integer.
|
||||||
@@ -81,32 +74,44 @@ Here's a summary of each level:
|
|||||||
|
|
||||||
## API groups
|
## API groups
|
||||||
|
|
||||||
[API groups](https://git.k8s.io/community/contributors/design-proposals/api-machinery/api-group.md) make it easier to extend the Kubernetes API. The API group is specified in a REST path and in the `apiVersion` field of a serialized object.
|
[API groups](https://git.k8s.io/community/contributors/design-proposals/api-machinery/api-group.md)
|
||||||
|
make it easier to extend the Kubernetes API.
|
||||||
|
The API group is specified in a REST path and in the `apiVersion` field of a
|
||||||
|
serialized object.
|
||||||
|
|
||||||
Currently, there are several API groups in use:
|
Currently, there are several API groups in use:
|
||||||
|
|
||||||
- The *core* (also called *legacy*) group is found at REST path `/api/v1`. The core group is not specified
|
* The *core* (also called *legacy*) group is found at REST path `/api/v1`.
|
||||||
as part of the `apiVersion` field, for example, `apiVersion: v1`.
|
The core group is not specified as part of the `apiVersion` field, for
|
||||||
- The named groups are at REST path `/apis/$GROUP_NAME/$VERSION` and use `apiVersion: $GROUP_NAME/$VERSION`
|
example, `apiVersion: v1`.
|
||||||
(for example, `apiVersion: batch/v1`). You can find the full list of supported API groups in
|
* The named groups are at REST path `/apis/$GROUP_NAME/$VERSION` and use
|
||||||
[Kubernetes API reference](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/).
|
`apiVersion: $GROUP_NAME/$VERSION` (for example, `apiVersion: batch/v1`).
|
||||||
|
You can find the full list of supported API groups in
|
||||||
|
[Kubernetes API reference](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/).
|
||||||
|
|
||||||
The two paths that support extending the API with [custom resources](/docs/concepts/extend-kubernetes/api-extension/custom-resources/) are:
|
## Enabling or disabling API groups {#enabling-or-disabling}
|
||||||
|
|
||||||
- [CustomResourceDefinition](/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/)
|
Certain resources and API groups are enabled by default. You can enable or
|
||||||
for basic CRUD needs.
|
disable them by setting `--runtime-config` on the API server. The
|
||||||
- [aggregator](https://github.com/kubernetes/community/blob/master/contributors/design-proposals/api-machinery/aggregated-api-servers.md) for a full set of Kubernetes API semantics to implement their own API server.
|
`--runtime-config` flag accepts comma separated `<key>=<value>` pairs
|
||||||
|
describing the runtime configuration of the API server. For example:
|
||||||
|
|
||||||
## Enabling or disabling API groups
|
- to disable `batch/v1`, set `--runtime-config=batch/v1=false`
|
||||||
|
- to enable `batch/v2alpha1`, set `--runtime-config=batch/v2alpha1`
|
||||||
Certain resources and API groups are enabled by default. You can enable or disable them by
|
|
||||||
setting `--runtime-config` on the API server. The `--runtime-config` flag accepts comma separated
|
|
||||||
key=value pairs describing the runtime configuration of the API server. For example:
|
|
||||||
|
|
||||||
- to disable batch/v1, set `--runtime-config=batch/v1=false`
|
|
||||||
- to enable batch/v2alpha1, set `--runtime-config=batch/v2alpha1`
|
|
||||||
|
|
||||||
{{< note >}}
|
{{< note >}}
|
||||||
When you enable or disable groups or resources, you need to restart the API server and controller-manager
|
When you enable or disable groups or resources, you need to restart the API
|
||||||
to pick up the `--runtime-config` changes.
|
server and controller manager to pick up the `--runtime-config` changes.
|
||||||
{{< /note >}}
|
{{< /note >}}
|
||||||
|
|
||||||
|
## Persistence
|
||||||
|
|
||||||
|
Kubernetes stores its serialized state in terms of the API resources by writing them into
|
||||||
|
{{< glossary_tooltip term_id="etcd" >}}.
|
||||||
|
|
||||||
|
## {{% heading "whatsnext" %}}
|
||||||
|
|
||||||
|
- Learn more about [API conventions](https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#api-conventions)
|
||||||
|
- Read the design documentation for
|
||||||
|
[aggregator](https://github.com/kubernetes/community/blob/master/contributors/design-proposals/api-machinery/aggregated-api-servers.md)
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user