Improve API guidelines for subresources

[jpbetz]

I'd like to leverage https://github.com/kubernetes/kubernetes/pull/127320 as an opportunity to improve our API guidelines for subresources for future contributors. Let's accumulate knowledge that we should document here.

I'll start with some topics that we've noticed over the last few days:

• When should a subresource be introduced? For example, RBAC permissions can be set on subresources, allowing more fine grained access. But subresources also bypass any preexisting admission plugins/webhooks/policies that match the root resource.
• For subresources that either have the same kind as the root resource but where only certain field may be updated:
  • How should subresource validation be handled? Should changes to other fields be ignored or should validation fail (/ephemeralcontainers fails validation, for example). We should also document how GetResetFields() must implemented when fields are ignored.
  • How should root validation be handled? Making the fields read-only in the root resource makes it possible to control write access via RBAC on the subresource. When this approach is taken, how should kubectl be enhanced to support the subresource?
  • How should the generated client to updated? We typically don't generate a per-subresource path function, but we do often generate Update and Apply functions.

cc @iholder101 @tallclair @thockin @liggitt

[k8s-ci-robot]

@jpbetz: The label(s) sig/arch cannot be applied, because the repository doesn't have them.

In response to [this](https://github.com/kubernetes/community/issues/8130#issuecomment-2436568737): >/sig arch > Instructions for interacting with me using PR comments are available [here](https://git.k8s.io/community/contributors/guide/pull-requests.md). If you have questions or suggestions related to my behavior, please file an issue against the [kubernetes-sigs/prow](https://github.com/kubernetes-sigs/prow/issues/new?title=Prow%20issue:) repository.

[jpbetz]

/sig architecture