Improve API guidelines for subresources

[jpbetz]

I'd like to leverage kubernetes/kubernetes#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:

/sig arch

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-sigs/prow repository.

[jpbetz]

/sig architecture

[thockin]

subresources also bypass any preexisting admission plugins/webhooks/policies that match the root resource

That seems like something a gap we should fix? Maybe subresource should be able to (optionally) trigger admission?

[liggitt]

subresources also bypass any preexisting admission plugins/webhooks/policies that match the root resource

That seems like something a gap we should fix? Maybe subresource should be able to (optionally) trigger admission?

I'm pretty sure that's captured in kubernetes/kubernetes#84530, and has lots of thorny / juicy issues to work through if trying to route requests to a subresource to an admission plugin registered only for the parent resource.