Skip to content

Commit d4e1edf

Browse files
k8s-ci-robotk8s-ci-robot
authored
Merge pull request #23866 from tengqm/refactor-api-concept
Remove duplicated content in concepts and reference
2 parents 314820a + 3cc1371 commit d4e1edf

File tree

2 files changed

+114
-153
lines changed

2 files changed

+114
-153
lines changed

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

Lines changed: 50 additions & 94 deletions
Original file line numberDiff line numberDiff line change
@@ -16,29 +16,22 @@ card:
1616

1717
The core of Kubernetes' {{< glossary_tooltip text="control plane" term_id="control-plane" >}}
1818
is the {{< glossary_tooltip text="API server" term_id="kube-apiserver" >}}. The API server
19-
exposes an HTTP API that lets end users, different parts of your cluster, and external components
20-
communicate with one another.
19+
exposes an HTTP API that lets end users, different parts of your cluster, and
20+
external components communicate with one another.
2121

2222
The Kubernetes API lets you query and manipulate the state of objects in the Kubernetes API
2323
(for example: Pods, Namespaces, ConfigMaps, and Events).
2424

25-
API endpoints, resource types and samples are described in the [API Reference](/docs/reference/kubernetes-api/).
25+
Most operations can be performed through the
26+
[kubectl](/docs/reference/kubectl/overview/) command-line interface or other
27+
command-line tools, such as
28+
[kubeadm](/docs/reference/setup-tools/kubeadm/kubeadm/), which in turn use the
29+
API. However, you can also access the API directly using REST calls.
2630

27-
<!-- body -->
28-
29-
## API changes
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.
3033

31-
Any system that is successful needs to grow and change as new use cases emerge or existing ones change.
32-
Therefore, Kubernetes has design features to allow the Kubernetes API to continuously change and grow.
33-
The Kubernetes project aims to _not_ break compatibility with existing clients, and to maintain that
34-
compatibility for a length of time so that other projects have an opportunity to adapt.
35-
36-
In general, new API resources and new resource fields can be added often and frequently.
37-
Elimination of resources or fields requires following the
38-
[API deprecation policy](/docs/reference/using-api/deprecation-policy/).
39-
40-
What constitutes a compatible change, and how to change the API, are detailed in
41-
[API changes](https://git.k8s.io/community/contributors/devel/sig-architecture/api_changes.md#readme).
34+
<!-- body -->
4235

4336
## OpenAPI specification {#api-specification}
4437

@@ -78,95 +71,58 @@ You can request the response format using request headers as follows:
7871
<caption>Valid request header values for OpenAPI v2 queries</caption>
7972
</table>
8073

81-
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.
82-
83-
## API versioning
84-
85-
To make it easier to eliminate fields or restructure resource representations, Kubernetes supports
86-
multiple API versions, each at a different API path, such as `/api/v1` or
87-
`/apis/rbac.authorization.k8s.io/v1alpha1`.
88-
89-
Versioning is done at the API level rather than at the resource or field level to ensure that the
90-
API presents a clear, consistent view of system resources and behavior, and to enable controlling
91-
access to end-of-life and/or experimental APIs.
74+
Kubernetes implements an alternative Protobuf based serialization format that
75+
is primarily intended for intra-cluster communication. For more information
76+
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
77+
Interface Definition Language (IDL) files for each schema located in the Go
78+
packages that define the API objects.
9279

93-
The JSON and Protobuf serialization schemas follow the same guidelines for schema changes - all descriptions below cover both formats.
94-
95-
Note that API versioning and Software versioning are only indirectly related. The
96-
[Kubernetes Release Versioning](https://git.k8s.io/community/contributors/design-proposals/release/versioning.md)
97-
proposal describes the relationship between API versioning and software versioning.
98-
99-
Different API versions imply different levels of stability and support. The criteria for each level are described
100-
in more detail in the
101-
[API Changes](https://git.k8s.io/community/contributors/devel/sig-architecture/api_changes.md#alpha-beta-and-stable-versions)
102-
documentation. They are summarized here:
103-
104-
- Alpha level:
105-
- The version names contain `alpha` (e.g. `v1alpha1`).
106-
- May be buggy. Enabling the feature may expose bugs. Disabled by default.
107-
- Support for feature may be dropped at any time without notice.
108-
- The API may change in incompatible ways in a later software release without notice.
109-
- Recommended for use only in short-lived testing clusters, due to increased risk of bugs and lack of long-term support.
110-
- Beta level:
111-
- The version names contain `beta` (e.g. `v2beta3`).
112-
- Code is well tested. Enabling the feature is considered safe. Enabled by default.
113-
- Support for the overall feature will not be dropped, though details may change.
114-
- The schema and/or semantics of objects may change in incompatible ways in a subsequent beta or stable release. When this happens,
115-
we will provide instructions for migrating to the next version. This may require deleting, editing, and re-creating
116-
API objects. The editing process may require some thought. This may require downtime for applications that rely on the feature.
117-
- Recommended for only non-business-critical uses because of potential for incompatible changes in subsequent releases. If you have
118-
multiple clusters which can be upgraded independently, you may be able to relax this restriction.
119-
- **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.**
120-
- Stable level:
121-
- The version name is `vX` where `X` is an integer.
122-
- Stable versions of features will appear in released software for many subsequent versions.
123-
124-
## API groups
125-
126-
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).
127-
The API group is specified in a REST path and in the `apiVersion` field of a serialized object.
128-
129-
There are several API groups in a cluster:
80+
## API changes
13081

131-
1. The *core* group, also referred to as the *legacy* group, is at the REST path `/api/v1` and uses `apiVersion: v1`.
82+
Any system that is successful needs to grow and change as new use cases emerge or existing ones change.
83+
Therefore, Kubernetes has designed its features to allow the Kubernetes API to continuously change and grow.
84+
The Kubernetes project aims to _not_ break compatibility with existing clients, and to maintain that
85+
compatibility for a length of time so that other projects have an opportunity to adapt.
13286

133-
1. *Named* groups are at REST path `/apis/$GROUP_NAME/$VERSION`, and use `apiVersion: $GROUP_NAME/$VERSION`
134-
(e.g. `apiVersion: batch/v1`). The Kubernetes [API reference](/docs/reference/kubernetes-api/) has a
135-
full list of available API groups.
87+
In general, new API resources and new resource fields can be added often and frequently.
88+
Elimination of resources or fields requires following the
89+
[API deprecation policy](/docs/reference/using-api/deprecation-policy/).
13690

137-
There are two paths to extending the API with [custom resources](/docs/concepts/extend-kubernetes/api-extension/custom-resources/):
91+
What constitutes a compatible change, and how to change the API, are detailed in
92+
[API changes](https://git.k8s.io/community/contributors/devel/sig-architecture/api_changes.md#readme).
13893

139-
1. [CustomResourceDefinition](/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/)
140-
lets you declaratively define how the API server should provide your chosen resource API.
141-
1. You can also [implement your own extension API server](/docs/tasks/extend-kubernetes/setup-extension-api-server/)
142-
and use the [aggregator](/docs/tasks/extend-kubernetes/configure-aggregation-layer/)
143-
to make it seamless for clients.
94+
## API groups and versioning
14495

145-
## Enabling or disabling API groups
96+
To make it easier to eliminate fields or restructure resource representations,
97+
Kubernetes supports multiple API versions, each at a different API path, such
98+
as `/api/v1` or `/apis/rbac.authorization.k8s.io/v1alpha1`.
14699

147-
Certain resources and API groups are enabled by default. They can be enabled or disabled by setting `--runtime-config`
148-
as a command line option to the kube-apiserver.
100+
Versioning is done at the API level rather than at the resource or field level
101+
to ensure that the API presents a clear, consistent view of system resources
102+
and behavior, and to enable controlling access to end-of-life and/or
103+
experimental APIs.
149104

150-
`--runtime-config` accepts comma separated values. For example: to disable batch/v1, set
151-
`--runtime-config=batch/v1=false`; to enable batch/v2alpha1, set `--runtime-config=batch/v2alpha1`.
152-
The flag accepts comma separated set of key=value pairs describing runtime configuration of the API server.
105+
Refer to [API versions reference](/docs/reference/using-api/api-overview/#api-versioning)
106+
for more details on the API version level definitions.
153107

154-
{{< note >}}Enabling or disabling groups or resources requires restarting the kube-apiserver and the
155-
kube-controller-manager to pick up the `--runtime-config` changes.{{< /note >}}
108+
To make it easier to evolve and to extend its API, Kubernetes implements
109+
[API groups](/docs/reference/using-api/api-overview/#api-groups) that can be
110+
[enabled or disabled](/docs/reference/using-api/api-overview/#enabling-or-disabling).
156111

157-
## Persistence
112+
## API Extension
158113

159-
Kubernetes stores its serialized state in terms of the API resources by writing them into
160-
{{< glossary_tooltip term_id="etcd" >}}.
114+
The Kubernetes API can be extended in one of two ways:
161115

116+
1. [Custom resources](/docs/concepts/extend-kubernetes/api-extension/custom-resources/)
117+
let you declaratively define how the API server should provide your chosen resource API.
118+
1. You can also extend the Kubernetes API by implementing an
119+
[aggregation layer](/docs/concepts/extend-kubernetes/api-extension/apiserver-aggregation/).
162120

163121
## {{% heading "whatsnext" %}}
164122

165-
[Controlling API Access](/docs/reference/access-authn-authz/controlling-access/) describes
166-
how the cluster manages authentication and authorization for API access.
167-
168-
Overall API conventions are described in the
169-
[API conventions](https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#api-conventions)
170-
document.
171-
172-
API endpoints, resource types and samples are described in the [API Reference](/docs/reference/kubernetes-api/).
123+
- Learn how to extend the Kubernetes API by adding your own
124+
[CustomResourceDefinition](/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions/).
125+
- [Controlling API Access](/docs/reference/access-authn-authz/controlling-access/) describes
126+
how the cluster manages authentication and authorization for API access.
127+
- Learn about API endpoints, resource types and samples by reading
128+
[API Reference](/docs/reference/kubernetes-api/).

0 commit comments

Comments
 (0)