diff --git a/content/en/docs/concepts/overview/kubernetes-api.md b/content/en/docs/concepts/overview/kubernetes-api.md index aa09776753..4338c932d5 100644 --- a/content/en/docs/concepts/overview/kubernetes-api.md +++ b/content/en/docs/concepts/overview/kubernetes-api.md @@ -16,30 +16,23 @@ card: 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. +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 objects in the Kubernetes API (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. -## 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} 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: Valid request header values for OpenAPI v2 queries -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 -multiple API versions, each at a different API path, such as `/api/v1` or -`/apis/rbac.authorization.k8s.io/v1alpha1`. +Any system that is successful needs to grow and change as new use cases emerge or existing ones change. +Therefore, Kubernetes has designed its 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. -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. +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/). -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 -[Kubernetes Release Versioning](https://git.k8s.io/community/contributors/design-proposals/release/versioning.md) -proposal describes the relationship between API versioning and software versioning. +## API groups and versioning -Different API versions imply different levels of stability and support. The criteria for each level are described -in more detail in the -[API Changes](https://git.k8s.io/community/contributors/devel/sig-architecture/api_changes.md#alpha-beta-and-stable-versions) -documentation. They are summarized here: +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`. -- Alpha level: - - The version names contain `alpha` (e.g. `v1alpha1`). - - May be buggy. Enabling the feature may expose bugs. Disabled by default. - - Support for feature may be dropped at any time without notice. - - 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. +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. -## 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). -The API group is specified in a REST path and in the `apiVersion` field of a serialized object. +To make it easier to evolve and to extend its API, Kubernetes implements +[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`. - -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" >}}. +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" %}} -[Controlling API Access](/docs/reference/access-authn-authz/controlling-access/) describes -how the cluster manages authentication and authorization for API access. - -Overall API conventions are described in the -[API conventions](https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#api-conventions) -document. - -API endpoints, resource types and samples are described in the [API Reference](/docs/reference/kubernetes-api/). +- Learn how to extend the Kubernetes API by adding your own + [CustomResourceDefinition](/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/). +- [Controlling API Access](/docs/reference/access-authn-authz/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/). diff --git a/content/en/docs/reference/using-api/api-overview.md b/content/en/docs/reference/using-api/api-overview.md index ca777b15c7..3b39d72e18 100644 --- a/content/en/docs/reference/using-api/api-overview.md +++ b/content/en/docs/reference/using-api/api-overview.md @@ -18,95 +18,100 @@ This page provides an overview of the Kubernetes API. -The REST API is the fundamental fabric of Kubernetes. All operations and communications between components -and external user commands are REST API calls that the API Server handles. Consequently, everything in the Kubernetes +The REST API is the fundamental fabric of Kubernetes. All operations and +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 [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 -To eliminate fields or restructure resource representations, Kubernetes supports -multiple API versions, each at a different API path. For example: `/api/v1` or -`/apis/rbac.authorization.k8s.io/v1alpha1`. +The JSON and Protobuf serialization schemas follow the same guidelines for +schema changes. The following descriptions cover both formats. -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. -- Enable control access to deprecated or experimental APIs. - -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). +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: - Alpha: - 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 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 - and lack of long-term support. - + - The software is recommended for use only in short-lived testing clusters, + due to increased risk of bugs and lack of long-term support. + - Beta: - 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 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, - or recreating API objects. The editing process may not be straightforward. Migration may require - downtime for applications that rely on the feature. - - The software is not recommended for production uses. Subsequent releases may introduce - incompatible changes. If you have multiple clusters which can be upgraded independently, - you may be able to relax this restriction. - - Try the beta features and provide feedback. After the features exit beta, it may not be practical - to make more changes. + - The schema and/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, and + re-creating API objects. The editing process may not be straightforward. + The migration may require downtime for applications that rely on the feature. + - The software is not recommended for production uses. Subsequent releases + may introduce incompatible changes. If you have multiple clusters which + 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: - The version name is `vX` where `X` is an integer. - The stable versions of features appear in released software for many subsequent versions. ## 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: -- The *core* (also called *legacy*) group is found at REST path `/api/v1`. The core group is not specified - as part of the `apiVersion` field, for example, `apiVersion: v1`. -- The named groups are at REST path `/apis/$GROUP_NAME/$VERSION` and use `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 *core* (also called *legacy*) group is found at REST path `/api/v1`. + The core group is not specified as part of the `apiVersion` field, for + example, `apiVersion: v1`. +* The named groups are at REST path `/apis/$GROUP_NAME/$VERSION` and use + `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/) - for basic CRUD needs. -- [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. +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 `=` pairs +describing the runtime configuration of the API server. For example: -## Enabling or disabling API groups - -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` + - to disable `batch/v1`, set `--runtime-config=batch/v1=false` + - to enable `batch/v2alpha1`, set `--runtime-config=batch/v2alpha1` {{< note >}} -When you enable or disable groups or resources, you need to restart the API server and controller-manager -to pick up the `--runtime-config` changes. +When you enable or disable groups or resources, you need to restart the API +server and 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" >}}. + +## {{% 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) +