From 3edb9705703019c7a3829f393caed7415d389b08 Mon Sep 17 00:00:00 2001 From: Tim Bannister Date: Tue, 13 Oct 2020 00:41:14 +0100 Subject: [PATCH] Move API overview to be a Docsy section overview --- .../api-extension/custom-resources.md | 2 +- .../docs/concepts/overview/kubernetes-api.md | 6 +- .../kubernetes-objects.md | 4 +- content/en/docs/reference/_index.md | 2 +- .../access-authn-authz/authorization.md | 2 +- content/en/docs/reference/using-api/_index.md | 129 +++++++++++++++++- .../docs/reference/using-api/api-overview.md | 118 ---------------- .../reference/using-api/client-libraries.md | 2 +- .../reference/using-api/deprecation-policy.md | 2 +- static/_redirects | 1 + 10 files changed, 138 insertions(+), 130 deletions(-) delete mode 100644 content/en/docs/reference/using-api/api-overview.md diff --git a/content/en/docs/concepts/extend-kubernetes/api-extension/custom-resources.md b/content/en/docs/concepts/extend-kubernetes/api-extension/custom-resources.md index 9a84267445..dcfef3f6b6 100644 --- a/content/en/docs/concepts/extend-kubernetes/api-extension/custom-resources.md +++ b/content/en/docs/concepts/extend-kubernetes/api-extension/custom-resources.md @@ -16,7 +16,7 @@ methods for adding custom resources and how to choose between them. ## 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 diff --git a/content/en/docs/concepts/overview/kubernetes-api.md b/content/en/docs/concepts/overview/kubernetes-api.md index 7580287fb3..d3348849e7 100644 --- a/content/en/docs/concepts/overview/kubernetes-api.md +++ b/content/en/docs/concepts/overview/kubernetes-api.md @@ -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 diff --git a/content/en/docs/concepts/overview/working-with-objects/kubernetes-objects.md b/content/en/docs/concepts/overview/working-with-objects/kubernetes-objects.md index ab447cdcd6..716955ca06 100644 --- a/content/en/docs/concepts/overview/working-with-objects/kubernetes-objects.md +++ b/content/en/docs/concepts/overview/working-with-objects/kubernetes-objects.md @@ -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. diff --git a/content/en/docs/reference/_index.md b/content/en/docs/reference/_index.md index 06eeb347d8..b8d6189032 100644 --- a/content/en/docs/reference/_index.md +++ b/content/en/docs/reference/_index.md @@ -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 diff --git a/content/en/docs/reference/access-authn-authz/authorization.md b/content/en/docs/reference/access-authn-authz/authorization.md index 7a251726fb..dcc270f3cf 100644 --- a/content/en/docs/reference/access-authn-authz/authorization.md +++ b/content/en/docs/reference/access-authn-authz/authorization.md @@ -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 diff --git a/content/en/docs/reference/using-api/_index.md b/content/en/docs/reference/using-api/_index.md index 9d6b7c4e36..51c06024b5 100644 --- a/content/en/docs/reference/using-api/_index.md +++ b/content/en/docs/reference/using-api/_index.md @@ -1,4 +1,129 @@ --- -title: Using the Kubernetes API +title: Kubernetes API Overview +reviewers: +- erictune +- lavalamp +- jbeda +content_type: concept weight: 10 ---- \ No newline at end of file +card: + name: reference + weight: 50 + title: Overview of API +--- + + + +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/). + + + +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 `[=]` pairs +describing the runtime configuration of the API server. If the `=` +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) diff --git a/content/en/docs/reference/using-api/api-overview.md b/content/en/docs/reference/using-api/api-overview.md deleted file mode 100644 index 5ba48e9a79..0000000000 --- a/content/en/docs/reference/using-api/api-overview.md +++ /dev/null @@ -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 ---- - - - -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 -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 `[=]` pairs -describing the runtime configuration of the API server. If the `=` -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) - diff --git a/content/en/docs/reference/using-api/client-libraries.md b/content/en/docs/reference/using-api/client-libraries.md index 3939a59a76..c14f0fa9c7 100644 --- a/content/en/docs/reference/using-api/client-libraries.md +++ b/content/en/docs/reference/using-api/client-libraries.md @@ -12,7 +12,7 @@ API from various programming languages. -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. diff --git a/content/en/docs/reference/using-api/deprecation-policy.md b/content/en/docs/reference/using-api/deprecation-policy.md index d93bbc03c9..17840f195b 100644 --- a/content/en/docs/reference/using-api/deprecation-policy.md +++ b/content/en/docs/reference/using-api/deprecation-policy.md @@ -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 | diff --git a/static/_redirects b/static/_redirects index c66e93c1de..f17a70684b 100644 --- a/static/_redirects +++ b/static/_redirects @@ -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