Confusing explanation for ResourceQuota concept

[nnlkcncff]

https://kubernetes.io/docs/concepts/policy/resource-quotas/#object-count-quota
You can set quota for the total number of certain resources of all standard, namespaced resource types...
...
When using count/* resource quota, an object is charged against the quota if it exists in server storage.
...
It is also possible to do generic object count quota on a limited set of resources.

Two things are confusing in this section:

1. count/* — it's precieved as a wildcard mask as if it contains all the resources such as a pods, services, persistentvolumeclaims. But this doesn’t not work that way. Consider rewording or adding some information about the meaning, maybe as a warning block or as a note block.

kubectl create --namespace=default --filename /dev/stdin <<-EOF
	apiVersion: v1
	kind: ResourceQuota
	metadata:
	  name: wildcard-mask
	spec:
	  hard:
	    count/*: 1
EOF
The ResourceQuota "wildcard-mask" is invalid: spec.hard[count/*]: Invalid value: "count/*": name part must consist of alphanumeric characters, '-', '_' or '.', and must start and end with an alphanumeric character (e.g. 'MyName',  or 'my.name',  or '123-abc', regex used for validation is '([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9]')

2. quota for the total number of certain resources and generic object count quota means the same, so there could be two syntaxes for the same object, for example count/pods and pods. I found the only difference — you cannot set any quota in count/-less syntax except what mentioned in the table. The problem is the wording — it looks like you can specify something different using different syntaxes, but in fact it's the same things with some limitations for count/-less syntax. Consider rewording to highlight that this is just another syntax for the same resources (if I'm not mistaken).

P.S. Maybe I've mistaken about count/services.nodeports and count/services.loadbalancers — you could create a policy using these resources, but I didn't find them among the cluster resources in the command output (perhaps this is not the complete list of resources):

showAllResources() {
	getGroupResources() {
		for apiVersion in $( echo ${2} ); do
			echo -e "${apiVersion}:\n$(
				kubectl get --raw "${1}/${apiVersion}" | jq --raw-output '.resources[].name' | while IFS= read -r; do echo "\t${REPLY}"; done
			)\n"
		done
	}

	getGroupResources /api  "$( kubectl get --raw /api  | jq --raw-output '.versions[]' )"
	getGroupResources /apis "$( kubectl get --raw /apis | jq --raw-output '.groups[].preferredVersion.groupVersion' )"
}

showAllResources

[dipesh-rawat]

/language en

[sftim]

/retitle Confusing explanation for ResourceQuota concept
/kind bug
/triage accepted
/priority backlog

[pegasas]

/assign @pegasas

I will reword or add some information about the meaning and comes out with a solution for community review.

[pegasas]

Hi, @nnlkcncff

It seems owner @whitebear009 has solved #1 by by whitebeard10#2.
For #2, my suggestion is we should add a link to below paragraph.
Then count/pod and pod would be clear.
In my opinion, we should use pods in resource quota yaml, and counts/pods for directly use kubectl.

[nnlkcncff]

I've familiarized myself with PRs and here's what I think:

• whitebeard10@7a75850 — here's some clarification on the difference between count/<resource>.<group> and count/<resource>, but that's not the problem, it's all clear here

• https://github.com/kubernetes/website/pull/42685/files — clarifications via link to the examples, but they do not help to solve the ambiguity I was talking about

I try to restate to emphasize.

There is no ambiguity in using count/<resource>.<group> or count/<resource> — they represent the syntax for pointing to a resource in the API namespace. There is ambiguity in the use of these two syntaxes:

1. count/* syntax (either count/<resource>.<group> or count/<resource>):

kubectl create --namespace=default --filename /dev/stdin <<-EOF
	apiVersion: v1
	kind: ResourceQuota
	metadata:
	  name: count-syntax
	spec:
	  hard:
	    count/pods: 1
EOF

# or the same thing, but with a group
kubectl create --namespace=default --filename /dev/stdin <<-EOF
	apiVersion: v1
	kind: ResourceQuota
	metadata:
	  name: count-syntax-group
	spec:
	  hard:
	    count/pods.v1: 1
EOF

2. count/*-less syntax:

kubectl create --namespace=default --filename /dev/stdin <<-EOF
	apiVersion: v1
	kind: ResourceQuota
	metadata:
	  name: countless-syntax
	spec:
	  hard:
	    pods: 1
EOF

Then look at two quotes:

1. You can set quota for the total number of certain resources of all standard, namespaced resource types using the following syntax:

2. It is also possible to do generic object count quota on a limited set of resources:

It sound like the first quote is talking about one type of quota and the second quote is talking about another one. It looks like it could be a different quota type, but in both options it is still the same limit on the number of objects for one particular resource. Also before you see the table, you might think that both quotes are talking about different types of resources.

It'll be much more clear If you reword that something like this:

1. "You can set quota for the total number of one particular resource for certain resources of all standard, namespaced resource types using the following syntax:"
2. "There is another syntax only to set the same type of quota for certain resources:"

Then look at another quote:

When using count/* resource quota, an object is charged against the quota if it exists in server storage.

One might think this is an explanation of the special syntax count/*, which is a wildcard mask to specify a quota that controls more than one resource. But it isn’t.

It'll be much clearer If you reword that something like this:

• "When using such a resource quota, an object is charged against the quota if it exists in server storage."
• or "When using a resource quota, an object is charged against the quota if it exists in server storage."

---

An interesting thing turned up while writing this comment:

kubectl create --namespace=default --filename /dev/stdin <<-EOF
        apiVersion: v1
        kind: ResourceQuota
        metadata:
          name: countless-syntax-unsupported-resource
        spec:
          hard:
            v1/deployments: 1
EOF

This command with count-less syntax created a quota for resource which is not in a table!

[pegasas]

Thanks @nnlkcncff for clarification!
I've make another PR pending reviewing.

[pegasas]

/close

[k8s-ci-robot]

@pegasas: Closing this issue.

In response to this:

/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.