dynamic resource allocation: match API with actual implementation in 1.26

This copies back the API description from pkg/apis/core/types.go which got
changed as part of the code review.

The focus of the API comments shifted from describing how the API is used to
what it contains. The additional comments from the KEP get preserved as
commentary on the API.

The other change is the introduction if resource.k8s.io and making templates a
stand-alone object.

Co-authored-by: Kevin Klues <[email protected]>

Author: pohly