There is only 1 version per object in k8s 1.20 as can be checked by command:
kubectl api-resources
Also, creating custom objects with different versions is not allowed. AlreadyExists is thrown on trying.
In what use cases providing --api-version option is useful then?
Command:
kubectl api-resources
Print the supported API resources on the server. You can read more about this command and allowed options here. Supported flags are:
| Name | Shorthand | Default | Usage |
|---|---|---|---|
| api-group | Limit to resources in the specified API group. | ||
| cached | false | Use the cached list of resources if available. | |
| namespaced | true | If false, non-namespaced resources will be returned, otherwise returning namespaced resources by default. | |
| no-headers | false | When using the default or custom-column output format, don't print headers (default print headers). | |
| output | o | Output format. One of: wide | |
| sort-by | If non-empty, sort list of resources using specified field. The field can be either 'name' or 'kind'. | ||
| verbs | [] | Limit to resources that support the specified verbs. |
You can use --api-group option to limit to resources in the specified API group.
There also exist the command:
kubectl api-versions
and it prints the supported API versions on the server, in the form of "group/version". You can read more about it here.
You can also read more about API groups and versioning.
EDIT: In the comment:
No, see example "kubectl explain deployment --api-version v1". In other words: when there can be more then one api version of a resource?
you are referring to a completely different command which is kubectl explain. Option --api-version gets different explanations for particular API version (API group/version). You can read more about it here.