Kubernetes RESTMapper源码分析
1、概述
在 kubernetes API中，我们经常使用属于 GVK 或者 GVR 来区分特定的 kubernetes 资源。其中 GVK 是 Group Version Kind 的简称，而 GVR 则是 Group Version Resource 的简称。
Kind 是 API “顶级”资源对象的类型，每个资源对象都需要 Kind 来区分它自身代表的资源类型，例如，对于一个 Pod 的例子：
apiVersion: v1
kind: Pod
metadata:
labels:
app: nfs-client-provisioner
name: nfs-client-provisioner-6b7577544d-lngg2
namespace: default
.......
其中 kind 字段即代表该资源对象的类型。一般来说，在 kubernetes API 中有三种不同的 Kind：
- 单个资源对象的类型，最典型的就是刚才例子中提到的 Pod；
- 资源对象的列表类型，例如 PodList 以及 NodeList 等；
- 特殊类型以及非持久化操作的类型，很多这种类型的资源是 subresource， 例如用于绑定资源的 /binding、更新资源状态的 /status 以及读写资源实例数量的 /scale。
需要注意的是，同 Kind 不只可以出现在同一分组的不同版本中，如 apps/v1beta1 与 apps/v1，它还可能出现在不同的分组中，例如 Deployment 开始以 alpha 的特性出现在 extensions 分组，GA 之后被推进到 apps 组，所以为了严格区分不同的 Kind，需要组合 API Group、API Version 与 Kind 成为 GVK。
Resource 则是通过 HTTP 协议以 JSON 格式发送或者读取的资源展现形式，可以以单个资源对象展现，也可以以列表的形式展现。要正确的请求资源对象，API-Server 必须知道 apiVersion 与请求的资源，这样 API-Server 才能正确地解码请求信息，这些信息正是处于请求的资源路径中。一般来说，把 API Group、API Version 以及 Resource 组合成为 GVR 可以区分特定的资源请求路径，例如 /apis/batch/v1/jobs 就是请求所有的 jobs 信息。
GVR 常用于组合成 RESTful API 请求路径。例如，针对应用程序 v1 部署的 RESTful API 请求如下所示：
GET /apis/apps/v1/namespaces/{namespace}/deployments/{name}
通过获取资源的 JSON 或 YAML 格式的序列化对象，进而从资源的类型信息中可以获得该资源的 GVK。RESTMapper作为GVK到GVR的映射，通过 GVK 信息则可以获取要读取的资源对象的 GVR，进而构建 RESTful API 请求获取对应的资源。Kubernetes 定义了 RESTMapper 接口并带默认带有实现 DefaultRESTMapper。
RESTMapper作为GVK到GVR的映射，其主要作用是在ListerWatcher时， 根据Schema定义的类型GVK解析出GVR， 向apiserver发起http请求获取资源， 然后watch。
2、RESTMapper源码分析
2.1 什么是RESTMapper
先来看来什么是RESTMapper。RESTMapper是一个interface，定义在/pkg/api/meta/interfaces.go中:
// RESTMapper allows clients to map resources to kind, and map kind and version
// to interfaces for manipulating those objects. It is primarily intended for
// consumers of Kubernetes compatible REST APIs as defined in docs/devel/api-conventions.md.
//
// The Kubernetes API provides versioned resources and object kinds which are scoped
// to API groups. In other words, kinds and resources should not be assumed to be
// unique across groups.
//
// TODO: split into sub-interfaces
type RESTMapper interface {
// KindFor takes a partial resource and returns the single match. Returns an error if there are multiple matches
KindFor(resource schema.GroupVersionResource) (schema.GroupVersionKind, error)
// KindsFor takes a partial resource and returns the list of potential kinds in priority order
KindsFor(resource schema.GroupVersionResource) ([]schema.GroupVersionKind, error)
// ResourceFor takes a partial resource and returns the single match. Returns an error if there are multiple matches
ResourceFor(input schema.GroupVersionResource) (schema.GroupVersionResource, error)
// ResourcesFor takes a partial resource and returns the list of potential resource in priority order
ResourcesFor(input schema.GroupVersionResource) ([]schema.GroupVersionResource, error)
// RESTMapping identifies a preferred resource mapping for the provided group kind.
RESTMapping(gk schema.GroupKind, versions ...string) (*RESTMapping, error)
// RESTMappings returns all resource mappings for the provided group kind if no
// version search is provided. Otherwise identifies a preferred resource mapping for
// the provided version(s).
RESTMappings(gk schema.GroupKind, versions ...string) ([]*RESTMapping, error)
ResourceSingularizer(resource string) (singular string, err error)
}
关于RESTMapper的注释非常重要，“RESTMapper allows clients to map resources to kind, and map kind and version to interfaces for manipulating those objects”。也就是说，RESTMapper映射是指GVR(GroupVersionResource)和GVK(GroupVersionKind)的关系，可以通过GVR找到合适的GVK，并可以通过GVK生成一个RESTMapping。
2.2 什么是RESTMapping
再来看来RESTMapping，同样定义在/pkg/api/meta/interfaces.go中：
// RESTMapping contains the information needed to deal with objects of a specific
// resource and kind in a RESTful manner.
type RESTMapping struct {
// Resource is the GroupVersionResource (location) for this endpoint
Resource schema.GroupVersionResource
// GroupVersionKind is the GroupVersionKind (data format) to submit to this endpoint
GroupVersionKind schema.GroupVersionKind
// Scope contains the information needed to deal with REST Resources that are in a resource hierarchy
Scope RESTScope
}
RESTMapping包含Resource名称（GVR），及其对应的GVK，还有一个Scope(标明资源是否为root或者namespaced)。
那么RESTMapping怎么用呢？
比如/pkg/apiserver/api_installer.go中就有使用到RESTMapping中的Scope用来生成合适的URL(RESTScopeNameRoot和RESTScopeNameNamespace处理不同，详见以后对Apiserver的分析)。
2.3 什么是RESTScope
这里一并把RESTScope介绍掉，因为RESTScope接口也定义在/pkg/api/meta/interfaces.go中：
type RESTScopeName string
const (
RESTScopeNameNamespace RESTScopeName = "namespace"
RESTScopeNameRoot RESTScopeName = "root"
)
// RESTScope contains the information needed to deal with REST resources that are in a resource hierarchy
type RESTScope interface {
// Name of the scope
Name() RESTScopeName
}
目前有两种类型RESTScope：namespace和root，RESTScopeNamespace表明该资源是在Namespace下的，如pods，rc等；RESTScopeRoot标明资源是全局的，如nodes, pv等。RESTScope具体由restScope之实现。restScope定义在/pkg/api/meta/restmapper.go中，逻辑比较简单，这里就不在详细分析。
// Implements RESTScope interface
type restScope struct {
name RESTScopeName
}
func (r *restScope) Name() RESTScopeName {
return r.name
}
var RESTScopeNamespace = &restScope{
name: RESTScopeNameNamespace,
}
var RESTScopeRoot = &restScope{
name: RESTScopeNameRoot,
}
2.4 DefaultRESTMapper
DefaultRESTMapper实现了RESTMapper interface。为什么称为DefaultRESTMapper呢，因为DefaultRESTMapper定义了defaultGroupVersions。DefaultRESTMapper定义在/pkg/api/meta/restmapper.go中：
//DefaultRESTMapper中的resource是指GVR，kind是指GVK
//singular和plural都是GVR,singular指资源的单数形式，plural指资源的复数形式
type DefaultRESTMapper struct {
defaultGroupVersions []schema.GroupVersion
resourceToKind map[schema.GroupVersionResource]schema.GroupVersionKind
kindToPluralResource map[schema.GroupVersionKind]schema.GroupVersionResource
kindToScope map[schema.GroupVersionKind]RESTScope
singularToPlural map[schema.GroupVersionResource]schema.GroupVersionResource
pluralToSingular map[schema.GroupVersionResource]schema.GroupVersionResource
}
var _ RESTMapper = &DefaultRESTMapper{}
现在来详细分析DefaultRESTMapper的字段的涵义。
- defaultGroupVersions: 默认的GroupVersion，如v1，apps/v1等，一般一个DefaultRESTMapper只设一个默认的GroupVersion；
- resourceToKind：GVR(单数,复数)到GVK的map；
- kindToPluralResource：GVK到GVR(复数)的map；
- kindToScope：GVK到Scope的map；
- singularToPlural：GVR(单数)到GVR(复数)的map；
- pluralToSingular：GVR(复数)到GVR(单数)的map；
下面来分析DefaultRESTMapper的重要方法的实现。
1）NewDefaultRESTMapper方法
NewDefaultRESTMapper方法生成一个新的DefaultRESTMapper。
func NewDefaultRESTMapper(defaultGroupVersions []schema.GroupVersion) *DefaultRESTMapper {
resourceToKind := make(map[schema.GroupVersionResource]schema.GroupVersionKind)
kindToPluralResource := make(map[schema.GroupVersionKind]schema.GroupVersionResource)
kindToScope := make(map[schema.GroupVersionKind]RESTScope)
singularToPlural := make(map[schema.GroupVersionResource]schema.GroupVersionResource)
pluralToSingular := make(map[schema.GroupVersionResource]schema.GroupVersionResource)
// TODO: verify name mappings work correctly when versions differ
return &DefaultRESTMapper{
resourceToKind: resourceToKind,
kindToPluralResource: kindToPluralResource,
kindToScope: kindToScope,
defaultGroupVersions: defaultGroupVersions,
singularToPlural: singularToPlural,
pluralToSingular: pluralToSingular,
}
}
2）AddSpecific(kind schema.GroupVersionKind, plural, singular schema.GroupVersionResource, scope RESTScope)
AddSpecific方法主要是把具体的GVK、GVR和scope对应值加入到DefaultRESTMapper对应的字段中。
func (m *DefaultRESTMapper) AddSpecific(kind schema.GroupVersionKind, plural, singular schema.GroupVersionResource, scope RESTScope) {
m.singularToPlural[singular] = plural
m.pluralToSingular[plural] = singular
m.resourceToKind[singular] = kind
m.resourceToKind[plural] = kind
m.kindToPluralResource[kind] = plural
m.kindToScope[kind] = scope
}
3）Add(kind schema.GroupVersionKind, scope RESTScope)
Add方法根据的具体的GVK获取对应GVR单数和复数值，并将GVK、GVR和scope对应值加入到DefaultRESTMapper对应的字段中。
func (m *DefaultRESTMapper) Add(kind schema.GroupVersionKind, scope RESTScope) {
plural, singular := UnsafeGuessKindToResource(kind)
m.AddSpecific(kind, plural, singular, scope)
}
UnsafeGuessKindToResource方法可以根据GVK获取对应GVR单数和复数值。
// unpluralizedSuffixes is a list of resource suffixes that are the same plural and singular
// This is only is only necessary because some bits of code are lazy and don't actually use the RESTMapper like they should.
// TODO eliminate this so that different callers can correctly map to resources. This probably means updating all
// callers to use the RESTMapper they mean.
var unpluralizedSuffixes = []string{
"endpoints",
}
// UnsafeGuessKindToResource converts Kind to a resource name.
// Broken. This method only "sort of" works when used outside of this package. It assumes that Kinds and Resources match
// and they aren't guaranteed to do so.
func UnsafeGuessKindToResource(kind schema.GroupVersionKind) ( /*plural*/ schema.GroupVersionResource /*singular*/, schema.GroupVersionResource) {
kindName := kind.Kind
if len(kindName) == 0 {
return schema.GroupVersionResource{}, schema.GroupVersionResource{}
}
singularName := strings.ToLower(kindName)
// GVR（单数）
singular := kind.GroupVersion().WithResource(singularName)
// unfluralized后缀是一组复数和单数相同的资源
for _, skip := range unpluralizedSuffixes {
if strings.HasSuffix(singularName, skip) {
return singular, singular
}
}
// 组织GVR（复数）
switch string(singularName[len(singularName)-1]) {
case "s":
return kind.GroupVersion().WithResource(singularName + "es"), singular
case "y":
return kind.GroupVersion().WithResource(strings.TrimSuffix(singularName, "y") + "ies"), singular
}
return kind.GroupVersion().WithResource(singularName + "s"), singular
}
4）ResourceFor方法
ResourceFor()通过GVR(信息不一定要全)找到一个最匹配的已注册的GVR（m.pluralToSingular）。规则如下：
- 如果参数GVR没有有Resource，则返回错误。
- 如果参数GVR限定Group，Version和Resource，则匹配Group，Version和Resource；
- 如果参数GVR限定Group和Resource，则匹配Group和Resource；
- 如果参数GVR限定Version和Resource，则匹配Version和Resource；
- 如果参数GVR只有Resource，则匹配Resource。
- 如果系统中存在多个匹配，则返回错误(系统现在还不支持在不同的Group中定义相同的type)。
// 找到最匹配的注册GVR
func (m *DefaultRESTMapper) ResourceFor(resource schema.GroupVersionResource) (schema.GroupVersionResource, error) {
resources, err := m.ResourcesFor(resource)
if err != nil {
return schema.GroupVersionResource{}, err
}
if len(resources) == 1 {
return resources[0], nil
}
return schema.GroupVersionResource{}, &AmbiguousResourceError{PartialResource: resource, MatchingResources: resources}
}
func (m *DefaultRESTMapper) ResourcesFor(input schema.GroupVersionResource) ([]schema.GroupVersionResource, error) {
// 获取GVR，使资源小写，并将内部版本转换为""
resource := coerceResourceForMatching(input)
hasResource := len(resource.Resource) > 0
hasGroup := len(resource.Group) > 0
hasVersion := len(resource.Version) > 0
// 资源必须存在
if !hasResource {
return nil, fmt.Errorf("a resource must be present, got: %v", resource)
}
ret := []schema.GroupVersionResource{}
switch {
case hasGroup && hasVersion:
// 完全限定，比较GVR
// fully qualified. Find the exact match
for plural, singular := range m.pluralToSingular {
if singular == resource {
ret = append(ret, plural)
break
}
if plural == resource {
ret = append(ret, plural)
break
}
}
case hasGroup:
// 只限定GR，比较GR
// given a group, prefer an exact match. If you don't find one, resort to a prefix match on group
foundExactMatch := false
requestedGroupResource := resource.GroupResource()
for plural, singular := range m.pluralToSingular {
if singular.GroupResource() == requestedGroupResource {
foundExactMatch = true
ret = append(ret, plural)
}
if plural.GroupResource() == requestedGroupResource {
foundExactMatch = true
ret = append(ret, plural)
}
}
// 只限定G，比较Group
// if you didn't find an exact match, match on group prefixing. This allows storageclass.storage to match
// storageclass.storage.k8s.io
if !foundExactMatch {
for plural, singular := range m.pluralToSingular {
if !strings.HasPrefix(plural.Group, requestedGroupResource.Group) {
continue
}
if singular.Resource == requestedGroupResource.Resource {
ret = append(ret, plural)
}
if plural.Resource == requestedGroupResource.Resource {
ret = append(ret, plural)
}
}
}
case hasVersion:
// 限定VR，比较VR
for plural, singular := range m.pluralToSingular {
if singular.Version == resource.Version && singular.Resource == resource.Resource {
ret = append(ret, plural)
}
if plural.Version == resource.Version && plural.Resource == resource.Resource {
ret = append(ret, plural)
}
}
default:
// 只比较Resource，根据Resource匹配
for plural, singular := range m.pluralToSingular {
if singular.Resource == resource.Resource {
ret = append(ret, plural)
}
if plural.Resource == resource.Resource {
ret = append(ret, plural)
}
}
}
if len(ret) == 0 {
return nil, &NoResourceMatchError{PartialResource: resource}
}
sort.Sort(resourceByPreferredGroupVersion{ret, m.defaultGroupVersions})
return ret, nil
}
// 使资源小写，并将内部版本转换为未指定的（遗留行为）
// coerceResourceForMatching makes the resource lower case and converts internal versions to unspecified (legacy behavior)
func coerceResourceForMatching(resource schema.GroupVersionResource) schema.GroupVersionResource {
resource.Resource = strings.ToLower(resource.Resource)
if resource.Version == runtime.APIVersionInternal {
resource.Version = ""
}
return resource
}
5）KindFor方法
KindFor()通过GVR(信息不一定要全)找到一个最匹配的已注册的GVK。规则和ResourceFor()一样：
- 如果参数GVR没有有Resource，则返回错误。
- 如果参数GVR限定Group，Version和Resource，则匹配Group，Version和Resource；
- 如果参数GVR限定Group和Resource，则匹配Group和Resource；
- 如果参数GVR限定Version和Resource，则匹配Version和Resource；
- 如果参数GVR只有Resource，则匹配Resource。
- 如果系统中存在多个匹配，则返回错误(系统现在还不支持在不同的Group中定义相同的type)。
注意：维护m.resourceToKind关系时，GVR单数和复数都会和GVK做映射，具体逻辑参见AddSpecific方法。
// 根据GVR找到最匹配GVK
func (m *DefaultRESTMapper) KindFor(resource schema.GroupVersionResource) (schema.GroupVersionKind, error) {
kinds, err := m.KindsFor(resource)
if err != nil {
return schema.GroupVersionKind{}, err
}
if len(kinds) == 1 {
return kinds[0], nil
}
return schema.GroupVersionKind{}, &AmbiguousResourceError{PartialResource: resource, MatchingKinds: kinds}
}
func (m *DefaultRESTMapper) KindsFor(input schema.GroupVersionResource) ([]schema.GroupVersionKind, error) {
resource := coerceResourceForMatching(input)
hasResource := len(resource.Resource) > 0
hasGroup := len(resource.Group) > 0
hasVersion := len(resource.Version) > 0
if !hasResource {
return nil, fmt.Errorf("a resource must be present, got: %v", resource)
}
ret := []schema.GroupVersionKind{}
switch {
// fully qualified. Find the exact match
case hasGroup && hasVersion:
kind, exists := m.resourceToKind[resource]
if exists {
ret = append(ret, kind)
}
case hasGroup:
foundExactMatch := false
requestedGroupResource := resource.GroupResource()
for currResource, currKind := range m.resourceToKind {
if currResource.GroupResource() == requestedGroupResource {
foundExactMatch = true
ret = append(ret, currKind)
}
}
// if you didn't find an exact match, match on group prefixing. This allows storageclass.storage to match
// storageclass.storage.k8s.io
if !foundExactMatch {
for currResource, currKind := range m.resourceToKind {
if !strings.HasPrefix(currResource.Group, requestedGroupResource.Group) {
continue
}
if currResource.Resource == requestedGroupResource.Resource {
ret = append(ret, currKind)
}
}
}
case hasVersion:
for currResource, currKind := range m.resourceToKind {
if currResource.Version == resource.Version && currResource.Resource == resource.Resource {
ret = append(ret, currKind)
}
}
default:
for currResource, currKind := range m.resourceToKind {
if currResource.Resource == resource.Resource {
ret = append(ret, currKind)
}
}
}
if len(ret) == 0 {
return nil, &NoResourceMatchError{PartialResource: input}
}
sort.Sort(kindByPreferredGroupVersion{ret, m.defaultGroupVersions})
return ret, nil
}
6）ResourceSingularizer方法
将资源名称从复数转换为单数，如果系统中存在多个匹配，则返回错误。
// 将资源名称从复数转换为单数
// ResourceSingularizer implements RESTMapper
// It converts a resource name from plural to singular (e.g., from pods to pod)
func (m *DefaultRESTMapper) ResourceSingularizer(resourceType string) (string, error) {
partialResource := schema.GroupVersionResource{Resource: resourceType}
resources, err := m.ResourcesFor(partialResource)
if err != nil {
return resourceType, err
}
singular := schema.GroupVersionResource{}
for _, curr := range resources {
currSingular, ok := m.pluralToSingular[curr]
if !ok {
continue
}
if singular.Empty() {
singular = currSingular
continue
}
if currSingular.Resource != singular.Resource {
return resourceType, fmt.Errorf("multiple possible singular resources (%v) found for %v", resources, resourceType)
}
}
if singular.Empty() {
return resourceType, fmt.Errorf("no singular of resource %v has been defined", resourceType)
}
return singular.Resource, nil
}
7）RESTMapping方法
根据GVK获取RESTMapping，RESTMapping()的参数是GK和versions，通常的做法是把一个GVK直接拆成GK和Version，然后获取mapping。
// RESTMapping returns a struct representing the resource path and conversion interfaces a
// RESTClient should use to operate on the provided group/kind in order of versions. If a version search
// order is not provided, the search order provided to DefaultRESTMapper will be used to resolve which
// version should be used to access the named group/kind.
func (m *DefaultRESTMapper) RESTMapping(gk schema.GroupKind, versions ...string) (*RESTMapping, error) {
mappings, err := m.RESTMappings(gk, versions...)
if err != nil {
return nil, err
}
if len(mappings) == 0 {
return nil, &NoKindMatchError{GroupKind: gk, SearchedVersions: versions}
}
// since we rely on RESTMappings method
// take the first match and return to the caller
// as this was the existing behavior.
return mappings[0], nil
}
// RESTMappings returns the RESTMappings for the provided group kind. If a version search order
// is not provided, the search order provided to DefaultRESTMapper will be used.
func (m *DefaultRESTMapper) RESTMappings(gk schema.GroupKind, versions ...string) ([]*RESTMapping, error) {
mappings := make([]*RESTMapping, 0)
// DefaultRESTMapper对象已注册最匹配的GVK
potentialGVK := make([]schema.GroupVersionKind, 0)
hadVersion := false
// 选择一个合适的版本， 找到DefaultRESTMapper对象最匹配的已注册的GVK
// Pick an appropriate version
for _, version := range versions {
if len(version) == 0 || version == runtime.APIVersionInternal {
continue
}
currGVK := gk.WithVersion(version)
hadVersion = true
if _, ok := m.kindToPluralResource[currGVK]; ok {
potentialGVK = append(potentialGVK, currGVK)
break
}
}
// version不满足条件的话，使用DefaultRESTMapper对象默认GV
// Use the default preferred versions
if !hadVersion && len(potentialGVK) == 0 {
for _, gv := range m.defaultGroupVersions {
if gv.Group != gk.Group {
continue
}
potentialGVK = append(potentialGVK, gk.WithVersion(gv.Version))
}
}
if len(potentialGVK) == 0 {
return nil, &NoKindMatchError{GroupKind: gk, SearchedVersions: versions}
}
for _, gvk := range potentialGVK {
// 确保有GVR（复数）
//Ensure we have a REST mapping
res, ok := m.kindToPluralResource[gvk]
if !ok {
continue
}
// 确保有rest scope
// Ensure we have a REST scope
scope, ok := m.kindToScope[gvk]
if !ok {
return nil, fmt.Errorf("the provided version %q and kind %q cannot be mapped to a supported scope", gvk.GroupVersion(), gvk.Kind)
}
mappings = append(mappings, &RESTMapping{
Resource: res,
GroupVersionKind: gvk,
Scope: scope,
})
}
if len(mappings) == 0 {
return nil, &NoResourceMatchError{PartialResource: schema.GroupVersionResource{Group: gk.Group, Resource: gk.Kind}}
}
return mappings, nil
}
RESTMapping()的流程如下：
- 构造GVK：使用GK和Versions，或GK和DefaultGroupVersions，构造GVK；
- 获取GVR：从kindToPluralResource中获取GVR；
- 获取scope：从kindToScope中获取scope；
- 组装成RESTMapping并返回。
3、总结
RESTMapper可以从GVK获取GVR，并生成一个RESTMapping来处理该GVR。RESTMapping中有GVK、GVR、Scope信息。
