Define 'resource' in glossary #49706

gjenkins8 · 2025-02-10T16:54:03Z

Description

Add a definitions of 'API resource' and 'resource (infrastructure)' to the glossary. As the term "resource" is frequently used in the docs, the Kubernetes API itself, and in the community (but not actually defined).

Inspiration / definitions taken from:
https://kubernetes.io/docs/reference/using-api/api-concepts/#standard-api-terminology
https://stackoverflow.com/questions/52309496/difference-between-kubernetes-objects-and-resources
https://datatracker.ietf.org/doc/html/rfc7231#section-2

https://en.wikipedia.org/wiki/System_resource

Issue

Closes: #25903

linux-foundation-easycla · 2025-02-10T16:54:10Z

The committers listed above are authorized under a signed CLA.

✅ login: gjenkins8 / name: George Jenkins (acb85c3)

k8s-ci-robot · 2025-02-10T16:54:12Z

Welcome @gjenkins8!

It looks like this is your first PR to kubernetes/website 🎉. Please refer to our pull request process documentation to help your PR have a smooth ride to approval.

You will be prompted by a bot to use commands during the review process. Do not be afraid to follow the prompts! It is okay to experiment. Here is the bot commands documentation.

You can also check if kubernetes/website has its own contribution guidelines.

You may want to refer to our testing guide if you run into trouble with your tests not passing.

If you are having difficulty getting your pull request seen, please follow the recommended escalation practices. Also, for tips and tricks in the contribution process you may want to read the Kubernetes contributor cheat sheet. We want to make sure your contribution gets all the attention it needs!

Thank you, and welcome to Kubernetes. 😃

stmcginnis

One question, but otherwise this looks good to me.

/lgtm

stmcginnis · 2025-02-10T16:59:31Z

content/en/docs/reference/glossary/resource.md

+- fundamental
+---
+An entity in the Kubernetes type system, typically representing {{< glossary_tooltip text="objects" term_id="object" >}}.
+But sometime representing an operation on objects, such as a permission check.


Is there somewhere "resource" is used like this? Seems odd to me to consider a permission check as a resource.

From: https://kubernetes.io/docs/reference/using-api/api-concepts/#standard-api-terminology

smaller number of API resource types are virtual in that they often represent operations on objects, rather than objects, such as a permission check

I added this for completeness. It also isn't typically what I would think of as a "resource". But I did want to try and capture the definitions from existing material.

It's apparently because we use "object" specifically when referring to concrete resource types like pods (i.e. resources that "exist" in the cluster), whereas something like a CreateEviction, while still a resource, wouldn't be an object

So, a Pod is an object (it has spec, it has metadata). But the eviction subresource of a Pod is not an object. Both are (HTTP) resources - see https://datatracker.ietf.org/doc/html/rfc7231#page-7

netlify · 2025-02-10T17:03:59Z

✅ Pull request preview available for checking

Built without sensitive environment variables

Name	Link
🔨 Latest commit	`acb85c3`
🔍 Latest deploy log	https://app.netlify.com/sites/kubernetes-io-main-staging/deploys/67b156dc7fa81d00084d51ca
😎 Deploy Preview	https://deploy-preview-49706--kubernetes-io-main-staging.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

content/en/docs/reference/glossary/object.md

shannonxtreme · 2025-02-10T18:37:45Z

content/en/docs/reference/glossary/resource.md

@@ -0,0 +1,17 @@
+---
+title: Resource


I think that we should make this term "API resource". There's already an overlap of the term resource in the context of the API and in the context of CPU and memory resources. If we're talking about an API resource in a document, especially the first time that we use the term, we should be calling it "API resource" to eliminate that ambiguity.

sftim

I really appreciate the work, but: we should improve it before we merge it.

/lgtm cancel

sftim · 2025-02-10T23:18:23Z

content/en/docs/reference/glossary/resource.md

+date: 2025-02-09
+full_link: https://kubernetes.io/docs/reference/using-api/api-concepts/#standard-api-terminology
+short_description: >
+  A Kubernetes entity, representing a RESTful endpoint on the Kubernetes API server


Kubernetes' API architecture is heavily inspired by ReST, but we can't be sure that all resources are part of ReST-like APIs. For example, Pods have various subresources that are more like RPC or streaming services (they don't have defined representations).

fair, I think best to simply remove "RESTful" then.

sftim · 2025-02-10T23:18:24Z

content/en/docs/reference/glossary/resource.md

There are multiple meanings of resource. Unlike most entries, this one needs to list at least the two most common meaning of resource. If not, we should make a separate entry for "HTTP resource" - very similar to the suggestion in https://github.com/kubernetes/website/pull/49706/files#r1949684500 - and ensure the two entries reference each other.

Here are the meanings I can think of:

Resource as in "something you might consume"; limits and requests are resource limits and resource requests

Web resources; for HTTP, a resource is something with a URI where the scheme is http or https. Especially, part of the Kubernetes HTTP API. Custom resources are resources in this sense.

sometimes, rarely: an API kind (eg thinking of Deployment as a resource)

Thanks, yes. I was originally targeting this toward the second meaning (of course). And I agree, ensuring it is clear both (or perhaps all three) of these concepts exist. And disambiguating between them should be done.

Thinking out loud -- perhaps there could be entries for "resource" and e.g. "compute resource" terms?

It might be confusing to have the second defined as "HTTP Resource", as a lot of existing terms already refer resource directly e.g.
https://kubernetes.io/docs/reference/glossary/?extension=true#term-CustomResourceDefinition
https://kubernetes.io/docs/reference/glossary/?all=true#term-helm-chart
https://kubernetes.io/docs/reference/glossary/?all=true#term-name

Personally, when someone mentions "resource" in the context of Kubernetes, I think of the API. Typically resource would need to be mentioned in the context of e.g. a Pod or compute to think of the first definition.

I think it will confuse people if we refer to memory as a compute resource.

…

Some people will think of the "amount of hardware" meaning and some will think of web architecture.

For the moment, I'll write both of these definitions into the PR. Then can split into separate glossary terms if/as desired.

I think it will confuse people if we refer to memory as a compute resource.

To note "compute resources" is used here with respect to :
https://kubernetes.io/docs/reference/glossary/?all=true#term-limitrange
https://kubernetes.io/docs/reference/glossary/?all=true#term-resource-quota

content/en/docs/reference/glossary/resource.md

gjenkins8 · 2025-02-12T06:15:23Z

@sftim -- I've split API resource vs Compute resource. Hopefully the definitions read well. Feedback appreciated!

(not sure if my definition of compute resource is the best. Its tricky to define these fundamental things from basic terminology!)

sftim

We try not to merge changes where one part is not correct, and unfortunately the part about resources always being node-local needs to change before I'd be happy to say Yes.

I do want this to merge and I think the next iteration will be good to go.

sftim · 2025-02-12T09:16:15Z

content/en/docs/reference/glossary/api-resource.md

+An entity in the Kubernetes type system, corresponding to an API endpoint on the {{< glossary_tooltip text="Kubernetes API" term_id="kubernetes-api" >}}.
+A resource typically represents an {{< glossary_tooltip text="objects" term_id="object" >}}.
+But sometime represents an operation on objects, such as a permission check.
+<!--more-->
+API resources compromise the Kubernetes type system which makes up the majority of the Kubernetes API.
+Each resource represents an endpoint on the Kubernetes API server, defining the schema for the objects or operations on that resource.


Would be great to mention that these are resources in the HTTP sense.

good point, I've added in HTTP and URI terms

sftim · 2025-02-12T09:17:17Z

content/en/docs/reference/glossary/compute-resource.md

+tags:
+- fundamental
+---
+Capability of {{< glossary_tooltip text="nodes" term_id="node" >}} available for consumption (CPU, memory, etc) by processes or users of those nodes.


Because of dynamic resource allocation these capabilities may not be node local.

For example, you can allocate an attachable GPU as a resource, even though 8 different nodes are all able to request attachment.

fair: s/of/provided by/

content/en/docs/reference/glossary/object.md

content/en/docs/reference/glossary/api-resource.md

content/en/docs/reference/glossary/compute-resource.md

content/en/docs/reference/glossary/infrastructure-resource.md

gjenkins8 · 2025-02-14T17:28:26Z

Thanks again @sftim ! (API) Resources vs objects was an itch I've wanted to scratch for some time :). I appreciate the help / guidance for the PR, and helping me make the contribution.

Two final thoughts from a final proof read on my part:

content/en/docs/reference/glossary/api-resource.md

content/en/docs/reference/glossary/infrastructure-resource.md

content/en/docs/reference/glossary/object.md

content/en/docs/reference/glossary/api-resource.md

content/en/docs/reference/glossary/infrastructure-resource.md

gjenkins8 · 2025-02-14T20:05:58Z

@sftim -- final cleanups done. I think all good to merge now. Thanks!

sftim · 2025-02-15T15:07:51Z

/lgtm

If you know how to squash commits on a pull request, please do that @gjenkins8 (it's tidier). If you've never used git rebase before, that's OK - doing that squash is optional. We can get Tide to trigger a similar but less tidy thing automatically (and I've already added the label to request this).

Next step is PR approval. Because this is a change to the live site, I'll only approve it if another org member adds their /lgtm on behalf of SIG Docs. Alternatively, a different approver can approve it right away.

k8s-ci-robot · 2025-02-15T15:07:57Z

LGTM label has been added.

Git tree hash: ef13b53fcf2c84c3e0ae145a04728c78b8193ed2

Signed-off-by: George Jenkins <[email protected]> Co-authored-by: Shannon Kularathna <[email protected]> Co-authored-by: Tim Bannister <[email protected]>

gjenkins8 · 2025-02-16T03:21:00Z

If you know how to squash commits on a pull request, please do that @gjenkins8 (it's tidier).

Certainly, squashed commits

sftim · 2025-02-16T13:39:34Z

/lgtm
/remove-label tide/merge-method-squash

k8s-ci-robot · 2025-02-16T13:39:40Z

LGTM label has been added.

Git tree hash: 2fa068af073a06468102a7e3d4a51a85a171d3cb

natalisucks · 2025-02-21T00:28:30Z

/approve

k8s-ci-robot · 2025-02-21T00:28:44Z

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: natalisucks

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

~~content/en/docs/OWNERS~~ [natalisucks]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

sftim · 2025-02-21T08:14:43Z

@gjenkins8, you've made a really positive improvement to our docs. Thank you.

See https://kubernetes.io/docs/reference/glossary/?all=true#term-infrastructure-resource for example.

sftim · 2025-02-21T09:04:42Z

Building on this, I opened #49852

k8s-ci-robot added the language/en Issues or PRs related to English language label Feb 10, 2025

k8s-ci-robot requested review from natalisucks and shannonxtreme February 10, 2025 16:54

gjenkins8 changed the title ~~Define 'resource' in glossry~~ Define 'resource' in glossary Feb 10, 2025

stmcginnis reviewed Feb 10, 2025

View reviewed changes

k8s-ci-robot assigned stmcginnis Feb 10, 2025

k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Feb 10, 2025

shannonxtreme reviewed Feb 10, 2025

View reviewed changes

sftim reviewed Feb 10, 2025

View reviewed changes

k8s-ci-robot assigned sftim Feb 10, 2025

k8s-ci-robot removed the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Feb 10, 2025

k8s-ci-robot requested a review from stmcginnis February 10, 2025 23:20

sftim reviewed Feb 10, 2025

View reviewed changes

content/en/docs/reference/glossary/resource.md Outdated Show resolved Hide resolved

k8s-ci-robot added size/M Denotes a PR that changes 30-99 lines, ignoring generated files. and removed size/S Denotes a PR that changes 10-29 lines, ignoring generated files. labels Feb 12, 2025

gjenkins8 force-pushed the define_resource_glossary branch 4 times, most recently from c4e3355 to d21c1f9 Compare February 12, 2025 06:12

gjenkins8 force-pushed the define_resource_glossary branch 2 times, most recently from 31d1fd6 to da32ca6 Compare February 12, 2025 06:27

sftim reviewed Feb 12, 2025

View reviewed changes

k8s-ci-robot removed the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Feb 14, 2025

k8s-ci-robot requested a review from sftim February 14, 2025 17:03