Revise “Kubernetes API Concepts” #25299

sftim · 2020-11-29T21:30:40Z

Revise Kubernetes API Concepts [preview]

ℹ️ This PR includes a Sass (CSS) change to indent definition lists. I think the impact is OK but I wanted to call it out.

Note Concept pages should live inside https://kubernetes.io/docs/concepts/. I think this page is in the right section (reference) and the thing to change is its title. That can happen in a separate PR that just covers the retitling.

sftim · 2020-11-29T21:30:49Z

/sig api-machinery

netlify · 2020-11-29T21:40:01Z

✔️ Deploy Preview for kubernetes-io-main-staging ready!

🔨 Explore the source changes: 3fc2bcb

🔍 Inspect the deploy log: https://app.netlify.com/sites/kubernetes-io-main-staging/deploys/617561b5cc9a7c00083ee183

😎 Browse the preview: https://deploy-preview-25299--kubernetes-io-main-staging.netlify.app

content/en/docs/reference/using-api/api-concepts.md

tengqm · 2020-11-30T01:12:09Z

content/en/docs/reference/using-api/api-concepts.md


-Almost all object resource types support the standard HTTP verbs - GET, POST, PUT, PATCH, and DELETE. Kubernetes uses the term **list** to describe returning a collection of resources to distinguish from retrieving a single resource which is usually called a **get**.
+Almost all object resource types support the standard HTTP verbs - GET, POST, PUT, PATCH, and DELETE. Kubernetes uses the term **List** to describe returning a collection of resources to distinguish from retrieving a single resource which is usually called a **Get**.


Do NOT change list to List or get to Get to cause more confusion, please.

There are some reference for mapping verbs. Let's be careful when introducing this kind of spelling changes.
https://kubernetes.io/docs/reference/access-authn-authz/authorization/#determine-the-request-verb

I think I'd got confused between watch (the verb) and Watch (the noun). It's hard to document; I'm learning as I go to be honest.

I've revised my approach here (having learned the API enough to understand what this page is trying to say).

content/en/docs/reference/using-api/api-concepts.md

tengqm

I have no idea why we keep "beautifying" the doc without adding new meats or fixing defects. Such changes are difficult to diff and difficult to synchronize to localizations.

content/en/docs/reference/using-api/api-concepts.md

kbhawkey · 2020-12-01T15:18:28Z

content/en/docs/reference/using-api/api-concepts.md


 The verbs supported for each subresource will differ depending on the object - see the API documentation more information. It is not possible to access sub-resources across multiple resources - generally a new virtual resource type would be used if that becomes necessary.


 ## Efficient detection of changes

-To enable clients to build a model of the current state of a cluster, all Kubernetes object resource types are required to support consistent lists and an incremental change notification feed called a **watch**.  Every Kubernetes object has a `resourceVersion` field representing the version of that resource as stored in the underlying database. When retrieving a collection of resources (either namespace or cluster scoped), the response from the server will contain a `resourceVersion` value that can be used to initiate a watch against the server. The server will return all changes (creates, deletes, and updates) that occur after the supplied `resourceVersion`. This allows a client to fetch the current state and then watch for changes without missing any updates. If the client watch is disconnected they can restart a new watch from the last returned `resourceVersion`, or perform a new collection request and begin again. See [Resource Version Semantics](#resource-versions) for more detail.
+To enable clients to build a model of the current state of a cluster, all Kubernetes object resource types are required to support consistent lists and an incremental change notification feed called a **watch**.  Every Kubernetes object has a `resourceVersion` field representing the version of that resource as stored in the underlying database. When retrieving a collection of resources (either namespace or cluster scoped), the response from the server will contain a `resourceVersion` value that can be used to initiate a Watch against the server. The server will return all changes (creates, deletes, and updates) that occur after the supplied `resourceVersion`. This allows a client to fetch the current state and then watch for changes without missing any updates. If the client Watch is disconnected they can restart a new Watch from the last returned `resourceVersion`, or perform a new collection request and begin again. See [Resource Versions](#resource-versions) for more detail.


Could you use code block formatting around the watch term instead of double asterisks or capitalization?
Can you cleanup the "will contain" to "contains" and "will return" to "returns"
Edit:
If a client is disconnected from a watch, they can restart a new watch from the last returned resourceVersion, or perform a new collection request to receive updates again. See Resource Versions for more detail.

I've just realized that there are three meanings of “watch” in Kubernetes - it's a verb, watch (eg in RBAC); it's a noun, Watch, as well ~~(representing a structure in an API response for example)~~, and then the English word watch describes what you use those jargon terms to achieve.

I guess I need to work out which I think each of these is closest to and adjust styling to match.

I've omitted this change from the latest revision.

Now addressed, I think.

content/en/docs/reference/using-api/api-concepts.md

kbhawkey · 2020-12-01T16:13:31Z

content/en/docs/reference/using-api/api-concepts.md


 ### Watch bookmarks

-To mitigate the impact of short history window, we introduced a concept of `bookmark` watch event. It is a special kind of event to mark that all changes up to a given `resourceVersion` the client is requesting have already been sent. Object returned in that event is of the type requested by the request, but only `resourceVersion` field is set, e.g.:
+To mitigate the impact of short history window, Kubernetes provides `bookmark` Watch events. A _bookmark_ is a special kind of event to mark that all changes up to a given `resourceVersion` the client is requesting have already been sent. The object returned in that event is of the type requested by the request, but only `resourceVersion` field is set.


nit: To mitigate the impact of a short history window,

Possible edit?
A bookmark is a special kind of event that marks all changes occurring before a client requests a given resourceVersion as sent by the API server. The object returned in the bookmark event is the same as the type set in the client request, but only the resourceVersion field is set.

IIUC, the bookmark watch event should be spelled as BOOKMARK. As shown in the example on line 139.

Addressed, I think.

kbhawkey · 2020-12-01T17:31:54Z

content/en/docs/reference/using-api/api-concepts.md


 ## Retrieving large results sets in chunks

 {{< feature-state for_k8s_version="v1.9" state="beta" >}}

-On large clusters, retrieving the collection of some resource types may result in very large responses that can impact the server and client. For instance, a cluster may have tens of thousands of pods, each of which is 1-2kb of encoded JSON. Retrieving all pods across all namespaces may result in a very large response (10-20MB) and consume a large amount of server resources. Starting in Kubernetes 1.9 the server supports the ability to break a single large collection request into many smaller chunks while preserving the consistency of the total request. Each chunk can be returned sequentially which reduces both the total size of the request and allows user-oriented clients to display results incrementally to improve responsiveness.
+On large clusters, retrieving the collection of some resource types may result in very large responses that can impact the server and client. For instance, a cluster may have tens of thousands of pods, each of which is 1-2KiB of encoded JSON. Retrieving all pods across all namespaces may result in a very large response (10-20MB) and consume a large amount of server resources. The kube-apiserver supports the ability to break a single large collection request into many smaller chunks while preserving the consistency of the total request. Each chunk can be returned sequentially; this chunking reduces the size of each HTTP response message and also allows user-oriented clients to display results incrementally to improve responsiveness. Splitting retrieval over multiple HTTP responses means that if a client needs to retry a fetch, only the missing portion needs to be retransmitted.



What is a "user-oriented" client -- a web browser?
Possible edit?
Each chunk is returned sequentially. Chunking reduces the size of an HTTP response which improves responsiveness in user-oriented clients. When a message is split over multiple HTTP responses and the client retries a fetch, only the missing portion of the message needs to be retransmitted by the API server.

What is a "user-oriented" client -- a web browser?

Let's save dealing with that to another PR? This one is already quite involved. I'd rather make some improvements now than hold off making any until I fully understand the Kubernetes API.

kbhawkey · 2020-12-01T17:32:49Z

content/en/docs/reference/using-api/api-concepts.md


-Like a watch operation, a `continue` token will expire after a short amount of time (by default 5 minutes) and return a `410 Gone` if more results cannot be returned. In this case, the client will need to start from the beginning or omit the `limit` parameter.
+Like a Watch operation, a `continue` token expires after a defined amount of time (5 minutes by default). If more results cannot be returned the API server returns a 410 (Gone) status. On receiving a 410 (Gone) response, the client needs to make a new request (possibly omitting the `limit` parameter, or using a larger `limit`).


Check about formatting response codes and capitalization?

410 is the right code and isn't capitalized. “Gone” is the text that 410 represents, both in English and as commonly returned as the status string by HTTP/1.x servers. However, this is not an actual HTTP/1.1 response; those look like:

HTTP/1.1 410 Gone …

See https://tools.ietf.org/html/rfc7231#section-6.5.9 for an example of idiomatic representation in running text.

content/en/docs/reference/using-api/api-concepts.md

liggitt · 2021-08-30T15:17:44Z

I likely won't have time until after 1.23 enhancement freeze (9/9)

kbhawkey · 2021-09-26T22:46:15Z

content/en/docs/reference/using-api/api-concepts.md


-Kubernetes generally leverages standard RESTful terminology to describe the API concepts:
+You can view the [API reference](/docs/reference/kubernetes-api/) online,
+or read on to learn about the API in general.


nit: Line 27, You could end the sentence with "online".

kbhawkey · 2021-09-26T22:50:51Z

content/en/docs/reference/using-api/api-concepts.md

+Most Kubernetes API resource types are
+[objects](/docs/concepts/overview/working-with-objects/kubernetes-objects/#kubernetes-objects):
+they represent a concrete instance of a concept on the cluster, like a
+pod or namespace. A smaller number of API resource types are *virtual* in


nit: Are there two types of resource:

object

virtual

That's a question for WG API Expression, I think (I don't know the answer).

kbhawkey · 2021-09-26T22:55:48Z

content/en/docs/reference/using-api/api-concepts.md

+
+### API verbs
+
+Almost all object resource types support the standard HTTP verbs - GET, POST, PUT, PATCH,


I have a question about: "Almost all object resource types". Is this the same as:
A Kubernetes resource type that represents an object supports the HTTP verbs: GET, POST, ...

When are the Kubernetes verbs (lowercase) used (add this information)?

When are the Kubernetes verbs (lowercase) used?

Could you clarify that question? I infer you're asking on behalf of the reader. What is it that they want to know?

kbhawkey · 2021-09-26T22:58:08Z

content/en/docs/reference/using-api/api-concepts.md

+
+For PUT requests, Kubernetes internally classifies these as either **create** or **update**
+based on the state of the existing object. An **update** is different from a **patch**; the
+HTTP verb for a **patch** is PATCH.


This sentence seems redundant:
the HTTP verb for a patch is PATCH.

Maybe:

the HTTP verb for a patch is PATCH, not PUT.

?

kbhawkey · 2021-09-26T23:02:50Z

content/en/docs/reference/using-api/api-concepts.md

+## Resource URIs
+
+All resource types are either scoped by the cluster (`/apis/GROUP/VERSION/*`) or to a
+namespace (`/apis/GROUP/VERSION/namespaces/NAMESPACE/*`). A namespace-scoped resource


Could break up the sentence, "A namespace-scoped resource ..."
The API server (?) deletes the namespace-scoped resource when the namespace is deleted. Access to a resource type is controlled by authorization checks on the namespace scope.

kbhawkey · 2021-09-26T23:05:12Z

content/en/docs/reference/using-api/api-concepts.md


 * Cluster-scoped subresource: `GET /apis/GROUP/VERSION/RESOURCETYPE/NAME/SUBRESOURCE`
 * Namespace-scoped subresource: `GET /apis/GROUP/VERSION/namespaces/NAMESPACE/RESOURCETYPE/NAME/SUBRESOURCE`

-The verbs supported for each subresource will differ depending on the object - see the API documentation for more information. It is not possible to access sub-resources across multiple resources - generally a new virtual resource type would be used if that becomes necessary.
+The verbs supported for each subresource will differ depending on the object -


nit: replace "will differ"
Each sub-resource supports various verbs. For more information, see API Reference.

kbhawkey · 2021-09-26T23:11:01Z

content/en/docs/reference/using-api/api-concepts.md

-
-```console
+There are dozens of collection types (such as `PodList`, `ServiceList`,
+and `NodeList`) defined in the Kubernetes API.


kbhawkey · 2021-09-26T23:21:32Z

👋 @sftim .
I am in favor of moving this pull request forward. I am not sure whether there are remaining questions or comments (@liggitt @lavalamp )?
Can you check on the commits. I noticed that you included updates to the theme and generator sub-modules.
Thanks.

sftim · 2021-09-27T09:47:52Z

I fixed the submodules, thanks for spotting that.

Table is now GA

Use padding to make the lists stand out from surrounding text.

celestehorgan · 2021-11-01T16:46:36Z

We've waited on @liggitt and @lavalamp for final comment for approximately one month now; and as such, by lazy consensus I'm going to assume they have no more comments.

I'm gonna merge it! :D

/lgtm

k8s-ci-robot · 2021-11-01T16:46:56Z

LGTM label has been added.

Git tree hash: 9f56bdf4399b41f7e0ea5c312bf67ac9811a45e9

tengqm · 2021-11-02T04:57:29Z

/refactor

tengqm · 2021-11-02T04:57:50Z

/label refactor

k8s-ci-robot added the cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. label Nov 29, 2020

k8s-ci-robot added the sig/api-machinery Categorizes an issue or PR as relevant to SIG API Machinery. label Nov 29, 2020

k8s-ci-robot requested review from liggitt and smarterclayton November 29, 2020 21:30

k8s-ci-robot added sig/docs Categorizes an issue or PR as relevant to SIG Docs. size/L Denotes a PR that changes 100-499 lines, ignoring generated files. labels Nov 29, 2020

tengqm reviewed Nov 30, 2020

View reviewed changes

content/en/docs/reference/using-api/api-concepts.md Outdated Show resolved Hide resolved

tengqm reviewed Nov 30, 2020

View reviewed changes

content/en/docs/reference/using-api/api-concepts.md Outdated Show resolved Hide resolved

tengqm reviewed Nov 30, 2020

View reviewed changes

content/en/docs/reference/using-api/api-concepts.md Show resolved Hide resolved

tengqm reviewed Nov 30, 2020

View reviewed changes

content/en/docs/reference/using-api/api-concepts.md Outdated Show resolved Hide resolved

tengqm reviewed Nov 30, 2020

View reviewed changes

content/en/docs/reference/using-api/api-concepts.md Outdated Show resolved Hide resolved

tengqm reviewed Nov 30, 2020

View reviewed changes

content/en/docs/reference/using-api/api-concepts.md Outdated Show resolved Hide resolved

tengqm reviewed Nov 30, 2020

View reviewed changes

content/en/docs/reference/using-api/api-concepts.md Outdated Show resolved Hide resolved

tengqm reviewed Nov 30, 2020

View reviewed changes

content/en/docs/reference/using-api/api-concepts.md Outdated Show resolved Hide resolved

tengqm requested changes Nov 30, 2020

View reviewed changes

sftim commented Nov 30, 2020

View reviewed changes

content/en/docs/reference/using-api/api-concepts.md Outdated Show resolved Hide resolved

kbhawkey reviewed Dec 1, 2020

View reviewed changes

content/en/docs/reference/using-api/api-concepts.md Outdated Show resolved Hide resolved

kbhawkey reviewed Dec 1, 2020

View reviewed changes

content/en/docs/reference/using-api/api-concepts.md Outdated Show resolved Hide resolved

kbhawkey reviewed Dec 1, 2020

View reviewed changes

content/en/docs/reference/using-api/api-concepts.md Outdated Show resolved Hide resolved

kbhawkey reviewed Dec 1, 2020

View reviewed changes

content/en/docs/reference/using-api/api-concepts.md Show resolved Hide resolved

kbhawkey reviewed Dec 1, 2020

View reviewed changes

content/en/docs/reference/using-api/api-concepts.md Outdated Show resolved Hide resolved

kbhawkey reviewed Dec 1, 2020

View reviewed changes

content/en/docs/reference/using-api/api-concepts.md Outdated Show resolved Hide resolved

kbhawkey reviewed Dec 1, 2020

View reviewed changes

content/en/docs/reference/using-api/api-concepts.md Outdated Show resolved Hide resolved

This was referenced Sep 9, 2021

Clarify "resourceVersion unset" semantics in Watch #26064

Closed

Issue with k8s.io/docs/reference/access-authn-authz/rbac/ #29696

Closed

kbhawkey reviewed Sep 26, 2021

View reviewed changes

sftim force-pushed the 20201129_revise_api_reference branch 2 times, most recently from 759ae72 to 52c9ddd Compare September 27, 2021 09:45

k8s-ci-robot added the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Oct 22, 2021

sftim added 4 commits October 24, 2021 14:31

Revise API details page

a53db47

Bump Table API to v1

2ca81a1

Table is now GA

Rewrap API concepts page

a49c612

Add left indent for definition lists

3fc2bcb

Use padding to make the lists stand out from surrounding text.

sftim force-pushed the 20201129_revise_api_reference branch from 52c9ddd to 3fc2bcb Compare October 24, 2021 13:37

k8s-ci-robot removed the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Oct 24, 2021

k8s-ci-robot assigned celestehorgan Nov 1, 2021

k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Nov 1, 2021

k8s-ci-robot merged commit 1a8c641 into kubernetes:main Nov 1, 2021

k8s-ci-robot added the refactor Indicates a PR with large refactoring changes e.g. removes files or moves content label Nov 2, 2021

sftim deleted the 20201129_revise_api_reference branch December 8, 2021 22:01


		Almost all object resource types support the standard HTTP verbs - GET, POST, PUT, PATCH, and DELETE. Kubernetes uses the term list to describe returning a collection of resources to distinguish from retrieving a single resource which is usually called a get.
		Almost all object resource types support the standard HTTP verbs - GET, POST, PUT, PATCH, and DELETE. Kubernetes uses the term List to describe returning a collection of resources to distinguish from retrieving a single resource which is usually called a Get.


		Like a watch operation, a `continue` token will expire after a short amount of time (by default 5 minutes) and return a `410 Gone` if more results cannot be returned. In this case, the client will need to start from the beginning or omit the `limit` parameter.
		Like a Watch operation, a `continue` token expires after a defined amount of time (5 minutes by default). If more results cannot be returned the API server returns a 410 (Gone) status. On receiving a 410 (Gone) response, the client needs to make a new request (possibly omitting the `limit` parameter, or using a larger `limit`).


		### API verbs

		Almost all object resource types support the standard HTTP verbs - GET, POST, PUT, PATCH,

Revise “Kubernetes API Concepts” #25299

Revise “Kubernetes API Concepts” #25299

Conversation

sftim commented Nov 29, 2020 • edited Loading

sftim commented Nov 29, 2020

netlify bot commented Nov 29, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tengqm left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sftim Dec 9, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

liggitt commented Aug 30, 2021

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kbhawkey commented Sep 26, 2021

sftim commented Sep 27, 2021

celestehorgan commented Nov 1, 2021

k8s-ci-robot commented Nov 1, 2021

tengqm commented Nov 2, 2021

tengqm commented Nov 2, 2021

sftim commented Nov 29, 2020 •

edited

Loading

netlify bot commented Nov 29, 2020 •

edited

Loading

sftim Dec 9, 2020 •

edited

Loading