Inconsistent use of the term "resource"

[MikeSpreitzer]

This is a Bug Report

Problem:
The term "resource" is used in inconsistent ways in the user-facing documentation and some prominent usages diverge from the common usage in the code. Sometimes "resource" is used like an object type or collection and sometimes it refers to an individual. This would not be so bad if the doc and code stuck to the usual web convention that a "resource" is anything that a URL locates, but the Kubernetes code and doc takes more particular stands --- but different ones in different places.

For example, https://kubernetes.io/docs/reference/using-api/api-concepts/#standard-api-terminology says

• A resource type is the name used in the URL (pods, namespaces, services)
• ...
• A single instance of the resource type is called a resource

... and yet the introductory paragraph of that section contradicts itself in the parenthetic reference to "the subjectaccessreviews resource".

https://kubernetes.io/docs/reference/using-api/api-overview/#enabling-specific-resources-in-the-extensions-v1beta1-group also uses the term "resource" in the sense of a type rather than an instance.

In the code the predominant usage of the word "resource" is to refer to the type rather than the instance. For example, see https://github.com/kubernetes/apimachinery/blob/master/pkg/runtime/schema/group_version.go .

Proposed Solution:
Either adopt a consistent usage throughout or explicitly give up.

Page to Update:
Most of them.

[sftim]

In the code the predominant usage of the word "resource" is to refer to the type rather than the instance.

That's also what I'd pick to put in documentation. In fact, it could even be a glossary entry: “In Kubernetes, a resource is…”

[sftim]

/kind cleanup
/priority backlog

[tengqm]

/language en

[celestehorgan]

/wg naming

@kubernetes/wg-naming-leads I'm adding this to the backlog as lowest priority, as it is technically an naming/terminology issue? However it'll be at the bottom of the backlog.

[fejta-bot]

Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/lifecycle stale

[justaugustus]

/remove-lifecycle stale

[justaugustus]

/sig architecture

[justaugustus]

cc: @kubernetes/sig-architecture-leads

[sftim]

/triage accepted

[sftim]

The other big use of resources is to describe the things that limits and requests are limiting and / or requesting.

We might not be able to avoid using the same English word to mean different things in different places, but we can call out when it might not be clear.

[tengqm]

We might not be able to avoid using the same English word to mean different things in different places, but we can call out when it might not be clear.

In Chinese, a "resource" is always a "资源", difficult to differentiate too.

[celestehorgan]

Hi all,

We've taken a look at this issue in the most recent WG naming meeting.

We don't think there's an issue of language/inclusivity that needs to be addressed in this issue, so I'm going to remove the wg-naming tag.

However, as a writer, there is definitely a developer style guide issue at play here, which would be useful to talk about in the next SIG Docs meeting

[celestehorgan]

/remove wg-naming

[MikeSpreitzer]

And remember this is an issue not only for developers of the code, there is also the user-facing documentation.

[fejta-bot]

Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.

If this issue is safe to close now please do so with /close.

Send feedback to sig-contributor-experience at kubernetes/community.
/lifecycle stale

[MikeSpreitzer]

/remove-lifecycle stale

[sftim]

/wg api-expression
/lifecycle frozen

[sftim]

/remove-wg naming

[sftim]

See #30092 (comment) for a specific suggestion.

[k8s-triage-robot]

This issue has not been updated in over 1 year, and should be re-triaged.

You can:

• Confirm that this issue is still relevant with /triage accepted (org members only)
• Close this issue with /close

For more details on the triage process, see https://www.kubernetes.dev/docs/guide/issue-triage/

/remove-triage accepted

[tengqm]

With the glossary entry PR merged, I think we can close this one.
There could be an endless discussion about the definition of "resource" and that discussion may lead us to nowhere. A term has its semantics in a context without which it is always ambiguous.

I'm closing this one as completed.
Feel free to reopen it if there are practical ideas to improve it.
/close

[k8s-ci-robot]

@tengqm: Closing this issue.

In response to this:

With the glossary entry PR merged, I think we can close this one.
There could be an endless discussion about the definition of "resource" and that discussion may lead us to nowhere. A term has its semantics in a context without which it is always ambiguous.

I'm closing this one as completed.
Feel free to reopen it if there are practical ideas to improve it.
/close

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

[sftim]

There's no entry for “resource” in https://kubernetes.io/docs/reference/glossary/?all=true

/reopen

[k8s-ci-robot]

@sftim: Reopened this issue.

In response to this:

There's no entry for “resource” in https://kubernetes.io/docs/reference/glossary/?all=true

/reopen

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

[sftim]

/triage accepted
again

[k8s-triage-robot]

This issue has not been updated in over 1 year, and should be re-triaged.

You can:

• Confirm that this issue is still relevant with /triage accepted (org members only)
• Close this issue with /close

For more details on the triage process, see https://www.kubernetes.dev/docs/guide/issue-triage/

/remove-triage accepted