Move API overview to be a Docsy section overview
Tim Bannister
parent
18634747c9
commit
3edb970570
|
|
@ -16,7 +16,7 @@ methods for adding custom resources and how to choose between them.
|
|||
<!-- body -->
|
||||
## Custom resources
|
||||
|
||||
A *resource* is an endpoint in the [Kubernetes API](/docs/reference/using-api/api-overview/) that stores a collection of
|
||||
A *resource* is an endpoint in the [Kubernetes API](/docs/concepts/overview/kubernetes-api/) that stores a collection of
|
||||
[API objects](/docs/concepts/overview/working-with-objects/kubernetes-objects/) of a certain kind; for example, the built-in *pods* resource contains a collection of Pod objects.
|
||||
|
||||
A *custom resource* is an extension of the Kubernetes API that is not necessarily available in a default
|
||||
|
|
|
|||
|
|
@ -103,8 +103,8 @@ 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-overview/#api-groups) that can be
|
||||
[enabled or disabled](/docs/reference/using-api/api-overview/#enabling-or-disabling).
|
||||
[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 may serve the same
|
||||
|
|
@ -115,7 +115,7 @@ versions `v1` and `v1beta1` for the same resource. An object created by the
|
|||
`v1beta1` version can then be read, updated, and deleted by either the
|
||||
`v1beta1` or the `v1` versions.
|
||||
|
||||
Refer to [API versions reference](/docs/reference/using-api/api-overview/#api-versioning)
|
||||
Refer to [API versions reference](/docs/reference/using-api/#api-versioning)
|
||||
for more details on the API version level definitions.
|
||||
|
||||
## API Extension
|
||||
|
|
|
|||
|
|
@ -91,9 +91,9 @@ and the `spec` format for a Deployment can be found in
|
|||
|
||||
## {{% heading "whatsnext" %}}
|
||||
|
||||
* [Kubernetes API overview](/docs/reference/using-api/api-overview/) explains some more API concepts
|
||||
* Learn about the most important basic Kubernetes objects, such as [Pod](/docs/concepts/workloads/pods/).
|
||||
* Learn about [controllers](/docs/concepts/architecture/controller/) in Kubernetes
|
||||
* Learn about [controllers](/docs/concepts/architecture/controller/) in Kubernetes.
|
||||
* [Using the Kubernetes API](/docs/reference/using-api/) explains some more API concepts.
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -18,8 +18,8 @@ This section of the Kubernetes documentation contains references.
|
|||
|
||||
## API Reference
|
||||
|
||||
* [Kubernetes API Overview](/docs/reference/using-api/api-overview/) - Overview of the API for Kubernetes.
|
||||
* [Kubernetes API Reference {{< latest-version >}}](/docs/reference/generated/kubernetes-api/{{< latest-version >}}/)
|
||||
* [Using The Kubernetes API](/docs/reference/using-api/) - overview of the API for Kubernetes.
|
||||
|
||||
## API Client Libraries
|
||||
|
||||
|
|
|
|||
|
|
@ -52,7 +52,7 @@ Kubernetes reviews only the following API request attributes:
|
|||
* **Resource** - The ID or name of the resource that is being accessed (for resource requests only) -- For resource requests using `get`, `update`, `patch`, and `delete` verbs, you must provide the resource name.
|
||||
* **Subresource** - The subresource that is being accessed (for resource requests only).
|
||||
* **Namespace** - The namespace of the object that is being accessed (for namespaced resource requests only).
|
||||
* **API group** - The {{< glossary_tooltip text="API Group" term_id="api-group" >}} being accessed (for resource requests only). An empty string designates the [core API group](/docs/reference/using-api/api-overview/#api-groups).
|
||||
* **API group** - The {{< glossary_tooltip text="API Group" term_id="api-group" >}} being accessed (for resource requests only). An empty string designates the _core_ [API group](/docs/reference/using-api/#api-groups).
|
||||
|
||||
## Determine the Request Verb
|
||||
|
||||
|
|
|
|||
|
|
@ -1,4 +1,129 @@
|
|||
---
|
||||
title: Using the Kubernetes API
|
||||
title: Kubernetes API Overview
|
||||
reviewers:
|
||||
- erictune
|
||||
- lavalamp
|
||||
- jbeda
|
||||
content_type: concept
|
||||
weight: 10
|
||||
---
|
||||
card:
|
||||
name: reference
|
||||
weight: 50
|
||||
title: Overview of API
|
||||
---
|
||||
|
||||
<!-- overview -->
|
||||
|
||||
This section provides reference information for 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
|
||||
platform is treated as an API object and has a corresponding entry in the
|
||||
[API](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/).
|
||||
|
||||
The [Kubernetes API reference](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/)
|
||||
lists the API for Kubernetes version {{< param "version" >}}.
|
||||
|
||||
For general background information, read
|
||||
[The Kubernetes API](/docs/concepts/overview/kubernetes-api/).
|
||||
|
||||
<!-- body -->
|
||||
|
||||
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.
|
||||
|
||||
## API versioning
|
||||
|
||||
The JSON and Protobuf serialization schemas follow the same guidelines for
|
||||
schema changes. The following descriptions cover both formats.
|
||||
|
||||
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.
|
||||
|
||||
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 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.
|
||||
|
||||
- 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 support for a feature will not be dropped, though the 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, 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 >}}
|
||||
Please try 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.
|
||||
|
||||
There are several API groups in Kubernetes:
|
||||
|
||||
* 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" >}}/#-strong-api-groups-strong-).
|
||||
|
||||
## Enabling or disabling API groups {#enabling-or-disabling}
|
||||
|
||||
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. If the `=<value>`
|
||||
part is omitted, it is treated as if `=true` is specified. For example:
|
||||
|
||||
- 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.
|
||||
{{< /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)
|
||||
|
|
|
|||
|
|
@ -1,118 +0,0 @@
|
|||
---
|
||||
title: Kubernetes API Overview
|
||||
reviewers:
|
||||
- erictune
|
||||
- lavalamp
|
||||
- jbeda
|
||||
content_type: concept
|
||||
weight: 10
|
||||
card:
|
||||
name: reference
|
||||
weight: 50
|
||||
title: Overview of API
|
||||
---
|
||||
|
||||
<!-- overview -->
|
||||
|
||||
This page provides an overview of the Kubernetes API.
|
||||
|
||||
<!-- body -->
|
||||
|
||||
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" >}}/).
|
||||
|
||||
## API versioning
|
||||
|
||||
The JSON and Protobuf serialization schemas follow the same guidelines for
|
||||
schema changes. The following descriptions cover both formats.
|
||||
|
||||
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.
|
||||
|
||||
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 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.
|
||||
|
||||
- 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 support for a feature will not be dropped, though the 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, 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.
|
||||
|
||||
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" >}}/#-strong-api-groups-strong-).
|
||||
|
||||
## Enabling or disabling API groups {#enabling-or-disabling}
|
||||
|
||||
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. If the `=<value>`
|
||||
part is omitted, it is treated as if `=true` is specified. For example:
|
||||
|
||||
- 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.
|
||||
{{< /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)
|
||||
|
||||
|
|
@ -12,7 +12,7 @@ API from various programming languages.
|
|||
|
||||
|
||||
<!-- body -->
|
||||
To write applications using the [Kubernetes REST API](/docs/reference/using-api/api-overview/),
|
||||
To write applications using the [Kubernetes REST API](/docs/reference/using-api/),
|
||||
you do not need to implement the API calls and request/response types yourself.
|
||||
You can use a client library for the programming language you are using.
|
||||
|
||||
|
|
|
|||
|
|
@ -24,7 +24,7 @@ a deprecation policy for aspects of the system that are slated to be removed.
|
|||
Since Kubernetes is an API-driven system, the API has evolved over time to
|
||||
reflect the evolving understanding of the problem space. The Kubernetes API is
|
||||
actually a set of APIs, called "API groups", and each API group is
|
||||
independently versioned. [API versions](/docs/reference/using-api/api-overview/#api-versioning) fall
|
||||
independently versioned. [API versions](/docs/reference/using-api/#api-versioning) fall
|
||||
into 3 main tracks, each of which has different policies for deprecation:
|
||||
|
||||
| Example | Track |
|
||||
|
|
|
|||
|
|
@ -68,6 +68,7 @@
|
|||
/docs/api/ /docs/concepts/overview/kubernetes-api/ 301
|
||||
|
||||
/docs/api-reference/labels-annotations-taints/ /docs/reference/labels-annotations-taints/ 301
|
||||
/docs/reference/using-api/api-overview/ /docs/reference/using-api/ 301
|
||||
|
||||
/docs/concepts/abstractions/controllers/garbage-collection/ /docs/concepts/workloads/controllers/garbage-collection/ 301
|
||||
/docs/concepts/abstractions/controllers/statefulsets/ /docs/concepts/workloads/controllers/statefulset/ 301
|
||||
|
|
|
|||
Loading…
Reference in New Issue