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信息。

參考：https://fankangbest.github.io/2017/07/22/RESTMapper%E8%A7%A3%E8%AF%BB%28%E4%B8%80%29-DefaultRESTMapper-v1-5-2/