From c4763d99bec929d71a7b130a9da102d10e07b722 Mon Sep 17 00:00:00 2001 From: Ritikaa96 Date: Tue, 2 Jul 2024 18:15:17 +0530 Subject: [PATCH 1/3] added watch to glossary Signed-off-by: Ritikaa96 --- content/en/docs/reference/glossary/watch.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) create mode 100644 content/en/docs/reference/glossary/watch.md diff --git a/content/en/docs/reference/glossary/watch.md b/content/en/docs/reference/glossary/watch.md new file mode 100644 index 0000000000..f1770b540a --- /dev/null +++ b/content/en/docs/reference/glossary/watch.md @@ -0,0 +1,20 @@ +--- +title: Watch +id: watch +date: 2024-07-02 +full_link: /docs/reference/using-api/api-concepts/#api-verbs +short_description: > + A verb that is used to track changes to an object in Kubernetes as a stream. + +aka: +tags: +- core-object +- fundamental +--- +A verb that is used to track changes to an object in Kubernetes as a stream. It is used for the excellent detection of changes. + + + +A verb that is used to track changes to an object in Kubernetes as a stream. It is used for the excellent detection of changes when this request is made to Kubernetes API or when HTTP GET request is made with watch query. + +See [Efficient Detection of Changes in API Concepts](/docs/reference/using-api/api-concepts/#efficient-detection-of-changes) for more information. From 5053a95f53085b5fe9bcd6d7fe28896f4473d597 Mon Sep 17 00:00:00 2001 From: Ritikaa96 Date: Thu, 4 Jul 2024 19:39:12 +0530 Subject: [PATCH 2/3] Adding glossary tooltip for watch in k/docs Signed-off-by: Ritikaa96 --- .../docs/concepts/overview/working-with-objects/labels.md | 2 +- .../en/docs/concepts/workloads/controllers/deployment.md | 2 +- .../en/docs/reference/access-authn-authz/authorization.md | 2 +- .../access-authn-authz/certificate-signing-requests.md | 2 +- content/en/docs/reference/glossary/watch.md | 7 +++++-- content/en/docs/reference/using-api/api-concepts.md | 2 +- .../en/docs/tasks/job/automated-tasks-with-cron-jobs.md | 2 +- .../tutorials/stateful-application/basic-stateful-set.md | 2 +- 8 files changed, 12 insertions(+), 9 deletions(-) diff --git a/content/en/docs/concepts/overview/working-with-objects/labels.md b/content/en/docs/concepts/overview/working-with-objects/labels.md index 8a488206d9..93bb28dc3b 100644 --- a/content/en/docs/concepts/overview/working-with-objects/labels.md +++ b/content/en/docs/concepts/overview/working-with-objects/labels.md @@ -201,7 +201,7 @@ For example: `partition in (customerA, customerB),environment!=qa`. ### LIST and WATCH filtering -LIST and WATCH operations may specify label selectors to filter the sets of objects +LIST and {{< glossary_tooltip text="WATCH" term_id="watch" >}} operations may specify label selectors to filter the sets of objects returned using a query parameter. Both requirements are permitted (presented here as they would appear in a URL query string): diff --git a/content/en/docs/concepts/workloads/controllers/deployment.md b/content/en/docs/concepts/workloads/controllers/deployment.md index e39e6f0f81..c07886183d 100644 --- a/content/en/docs/concepts/workloads/controllers/deployment.md +++ b/content/en/docs/concepts/workloads/controllers/deployment.md @@ -813,7 +813,7 @@ apply multiple fixes in between pausing and resuming without triggering unnecess ``` deployment.apps/nginx-deployment resumed ``` -* Watch the status of the rollout until it's done. +* {{< glossary_tooltip text="Watch" term_id="watch" >}} the status of the rollout until it's done. ```shell kubectl get rs -w ``` diff --git a/content/en/docs/reference/access-authn-authz/authorization.md b/content/en/docs/reference/access-authn-authz/authorization.md index 6d4ebb0b60..d80d843bad 100644 --- a/content/en/docs/reference/access-authn-authz/authorization.md +++ b/content/en/docs/reference/access-authn-authz/authorization.md @@ -61,7 +61,7 @@ Kubernetes reviews only the following API request attributes: * **extra** - A map of arbitrary string keys to string values, provided by the authentication layer. * **API** - Indicates whether the request is for an API resource. * **Request path** - Path to miscellaneous non-resource endpoints like `/api` or `/healthz`. - * **API request verb** - API verbs like `get`, `list`, `create`, `update`, `patch`, `watch`, `delete`, and `deletecollection` are used for resource requests. To determine the request verb for a resource API endpoint, see [request verbs and authorization](/docs/reference/access-authn-authz/authorization/#determine-the-request-verb). + * **API request verb** - API verbs like `get`, `list`, `create`, `update`, `patch`, `{{< glossary_tooltip text="watch" term_id="watch" >}}`, `delete`, and `deletecollection` are used for resource requests. To determine the request verb for a resource API endpoint, see [request verbs and authorization](/docs/reference/access-authn-authz/authorization/#determine-the-request-verb). * **HTTP request verb** - Lowercased HTTP methods like `get`, `post`, `put`, and `delete` are used for non-resource requests. * **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). diff --git a/content/en/docs/reference/access-authn-authz/certificate-signing-requests.md b/content/en/docs/reference/access-authn-authz/certificate-signing-requests.md index e5eefc1d60..fe6b012dd7 100644 --- a/content/en/docs/reference/access-authn-authz/certificate-signing-requests.md +++ b/content/en/docs/reference/access-authn-authz/certificate-signing-requests.md @@ -407,7 +407,7 @@ the bundle with their own arbitrary but stable ordering. ClusterTrustBundle objects should be considered world-readable within the cluster. If your cluster uses [RBAC](/docs/reference/access-authn-authz/rbac/) authorization, all ServiceAccounts have a default grant that allows them to -**get**, **list**, and **watch** all ClusterTrustBundle objects. +**get**, **list**, and **{{< glossary_tooltip text="watch" term_id="watch" >}}** all ClusterTrustBundle objects. If you use your own authorization mechanism and you have enabled ClusterTrustBundles in your cluster, you should set up an equivalent rule to make these objects public within the cluster, so that they work as intended. diff --git a/content/en/docs/reference/glossary/watch.md b/content/en/docs/reference/glossary/watch.md index f1770b540a..e2f4ff7418 100644 --- a/content/en/docs/reference/glossary/watch.md +++ b/content/en/docs/reference/glossary/watch.md @@ -8,13 +8,16 @@ short_description: > aka: tags: -- core-object +- API verb - fundamental --- A verb that is used to track changes to an object in Kubernetes as a stream. It is used for the excellent detection of changes. -A verb that is used to track changes to an object in Kubernetes as a stream. It is used for the excellent detection of changes when this request is made to Kubernetes API or when HTTP GET request is made with watch query. +A verb that is used to track changes to an object in Kubernetes as a stream. Watches allow +efficient detection of changes; for example, a +{{< glossary_tooltip term_id="controller" text="controller">}} that needs to know whenever a +ConfigMap has changed can use a watch rather than polling. See [Efficient Detection of Changes in API Concepts](/docs/reference/using-api/api-concepts/#efficient-detection-of-changes) for more information. diff --git a/content/en/docs/reference/using-api/api-concepts.md b/content/en/docs/reference/using-api/api-concepts.md index acd54e8030..36df9e8e9f 100644 --- a/content/en/docs/reference/using-api/api-concepts.md +++ b/content/en/docs/reference/using-api/api-concepts.md @@ -19,7 +19,7 @@ fine grained authorization (such as separate views for Pod details and log retrievals), and can accept and serve those resources in different representations for convenience or efficiency. -Kubernetes supports efficient change notifications on resources via *watches*. +Kubernetes supports efficient change notifications on resources via *{{< glossary_tooltip text="watches" term_id="watch" >}}*. Kubernetes also provides consistent list operations so that API clients can effectively cache, track, and synchronize the state of resources. diff --git a/content/en/docs/tasks/job/automated-tasks-with-cron-jobs.md b/content/en/docs/tasks/job/automated-tasks-with-cron-jobs.md index af9cd0c95e..1f91a2da87 100644 --- a/content/en/docs/tasks/job/automated-tasks-with-cron-jobs.md +++ b/content/en/docs/tasks/job/automated-tasks-with-cron-jobs.md @@ -49,7 +49,7 @@ hello */1 * * * * False 0 10s ``` As you can see from the results of the command, the cron job has not scheduled or run any jobs yet. -Watch for the job to be created in around one minute: +{{< glossary_tooltip text="Watch" term_id="watch" >}} for the job to be created in around one minute: ```shell kubectl get jobs --watch diff --git a/content/en/docs/tutorials/stateful-application/basic-stateful-set.md b/content/en/docs/tutorials/stateful-application/basic-stateful-set.md index 4fe4bb864f..f2ea4591b3 100644 --- a/content/en/docs/tutorials/stateful-application/basic-stateful-set.md +++ b/content/en/docs/tutorials/stateful-application/basic-stateful-set.md @@ -77,7 +77,7 @@ It creates a [headless Service](/docs/concepts/services-networking/service/#head {{% code_sample file="application/web/web.yaml" %}} You will need to use at least two terminal windows. In the first terminal, use -[`kubectl get`](/docs/reference/generated/kubectl/kubectl-commands/#get) to watch the creation +[`kubectl get`](/docs/reference/generated/kubectl/kubectl-commands/#get) to {{< glossary_tooltip text="watch" term_id="watch" >}} the creation of the StatefulSet's Pods. ```shell From 53dc63aec82e78b7e5174e9cd98382ac628c0165 Mon Sep 17 00:00:00 2001 From: Ritikaa96 Date: Mon, 8 Jul 2024 10:46:13 +0530 Subject: [PATCH 3/3] editing as per the reviews. Signed-off-by: Ritikaa96 --- .../docs/concepts/overview/working-with-objects/labels.md | 7 +++++-- .../en/docs/concepts/workloads/controllers/deployment.md | 2 +- .../en/docs/reference/access-authn-authz/authorization.md | 2 +- .../access-authn-authz/certificate-signing-requests.md | 2 +- content/en/docs/reference/glossary/watch.md | 3 ++- content/en/docs/reference/using-api/api-concepts.md | 4 +++- 6 files changed, 13 insertions(+), 7 deletions(-) diff --git a/content/en/docs/concepts/overview/working-with-objects/labels.md b/content/en/docs/concepts/overview/working-with-objects/labels.md index 93bb28dc3b..d12a84a30d 100644 --- a/content/en/docs/concepts/overview/working-with-objects/labels.md +++ b/content/en/docs/concepts/overview/working-with-objects/labels.md @@ -201,8 +201,11 @@ For example: `partition in (customerA, customerB),environment!=qa`. ### LIST and WATCH filtering -LIST and {{< glossary_tooltip text="WATCH" term_id="watch" >}} operations may specify label selectors to filter the sets of objects -returned using a query parameter. Both requirements are permitted +For **list** and **watch** operations, you can specify label selectors to filter the sets of objects +returned; you specify the filter using a query parameter. +(To learn in detail about watches in Kubernetes, read +[efficient detection of changes](/docs/reference/using-api/api-concepts/#efficient-detection-of-changes)). +Both requirements are permitted (presented here as they would appear in a URL query string): * _equality-based_ requirements: `?labelSelector=environment%3Dproduction,tier%3Dfrontend` diff --git a/content/en/docs/concepts/workloads/controllers/deployment.md b/content/en/docs/concepts/workloads/controllers/deployment.md index c07886183d..5dc8bfb6d4 100644 --- a/content/en/docs/concepts/workloads/controllers/deployment.md +++ b/content/en/docs/concepts/workloads/controllers/deployment.md @@ -815,7 +815,7 @@ apply multiple fixes in between pausing and resuming without triggering unnecess ``` * {{< glossary_tooltip text="Watch" term_id="watch" >}} the status of the rollout until it's done. ```shell - kubectl get rs -w + kubectl get rs --watch ``` The output is similar to this: diff --git a/content/en/docs/reference/access-authn-authz/authorization.md b/content/en/docs/reference/access-authn-authz/authorization.md index d80d843bad..6d4ebb0b60 100644 --- a/content/en/docs/reference/access-authn-authz/authorization.md +++ b/content/en/docs/reference/access-authn-authz/authorization.md @@ -61,7 +61,7 @@ Kubernetes reviews only the following API request attributes: * **extra** - A map of arbitrary string keys to string values, provided by the authentication layer. * **API** - Indicates whether the request is for an API resource. * **Request path** - Path to miscellaneous non-resource endpoints like `/api` or `/healthz`. - * **API request verb** - API verbs like `get`, `list`, `create`, `update`, `patch`, `{{< glossary_tooltip text="watch" term_id="watch" >}}`, `delete`, and `deletecollection` are used for resource requests. To determine the request verb for a resource API endpoint, see [request verbs and authorization](/docs/reference/access-authn-authz/authorization/#determine-the-request-verb). + * **API request verb** - API verbs like `get`, `list`, `create`, `update`, `patch`, `watch`, `delete`, and `deletecollection` are used for resource requests. To determine the request verb for a resource API endpoint, see [request verbs and authorization](/docs/reference/access-authn-authz/authorization/#determine-the-request-verb). * **HTTP request verb** - Lowercased HTTP methods like `get`, `post`, `put`, and `delete` are used for non-resource requests. * **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). diff --git a/content/en/docs/reference/access-authn-authz/certificate-signing-requests.md b/content/en/docs/reference/access-authn-authz/certificate-signing-requests.md index fe6b012dd7..e5eefc1d60 100644 --- a/content/en/docs/reference/access-authn-authz/certificate-signing-requests.md +++ b/content/en/docs/reference/access-authn-authz/certificate-signing-requests.md @@ -407,7 +407,7 @@ the bundle with their own arbitrary but stable ordering. ClusterTrustBundle objects should be considered world-readable within the cluster. If your cluster uses [RBAC](/docs/reference/access-authn-authz/rbac/) authorization, all ServiceAccounts have a default grant that allows them to -**get**, **list**, and **{{< glossary_tooltip text="watch" term_id="watch" >}}** all ClusterTrustBundle objects. +**get**, **list**, and **watch** all ClusterTrustBundle objects. If you use your own authorization mechanism and you have enabled ClusterTrustBundles in your cluster, you should set up an equivalent rule to make these objects public within the cluster, so that they work as intended. diff --git a/content/en/docs/reference/glossary/watch.md b/content/en/docs/reference/glossary/watch.md index e2f4ff7418..e1057ec882 100644 --- a/content/en/docs/reference/glossary/watch.md +++ b/content/en/docs/reference/glossary/watch.md @@ -11,7 +11,8 @@ tags: - API verb - fundamental --- -A verb that is used to track changes to an object in Kubernetes as a stream. It is used for the excellent detection of changes. +A verb that is used to track changes to an object in Kubernetes as a stream. +It is used for the efficient detection of changes. diff --git a/content/en/docs/reference/using-api/api-concepts.md b/content/en/docs/reference/using-api/api-concepts.md index 36df9e8e9f..baed3d8bed 100644 --- a/content/en/docs/reference/using-api/api-concepts.md +++ b/content/en/docs/reference/using-api/api-concepts.md @@ -19,7 +19,9 @@ fine grained authorization (such as separate views for Pod details and log retrievals), and can accept and serve those resources in different representations for convenience or efficiency. -Kubernetes supports efficient change notifications on resources via *{{< glossary_tooltip text="watches" term_id="watch" >}}*. +Kubernetes supports efficient change notifications on resources via +_watches_: +{{< glossary_definition prepend="in the Kubernetes API, watch is" term_id="watch" length="short" >}} Kubernetes also provides consistent list operations so that API clients can effectively cache, track, and synchronize the state of resources.