Kubernetes Clientset

忘是亡心i 2022-04-24 16:52 112阅读 0赞

# Kubernetes Clientset #

*  Kubernetes Clientset
    
     *  资源类型 Scheme
        
         *  types.go 文件
         *  zz\_generated.deepcopy.go 文件
         *  register.go 文件
     *  注册所有内置资源类型到 Scheme 对象
     *  创建和使用 Kubernetes Clientset
     *  创建支持所有资源类型的全局 Clientset
     *  各资源类型的 Clientset
     *  各资源类型的 RestFul 方法
     *  使用资源类型的 Clientset 创建 Informer 和 Lister
     *  使用 codegen 工具生成资源类型的 Clientset、Informer 和 Lister
     *  参考

## 资源类型 Scheme ##

Clienset 和 apiserver 通信时，需要根据资源对象的类型生成 Resource URL、对 Wire-data 进行**编解码(序列化/反序列化)**。

资源类型的 Group、Version、Kind、go struct 定义、编解码(序列化/反序列化) 等内容构成了它的 `Scheme`。

K8S 内置资源类型的 Scheme 位于 `k8s.io/api/<group>/<version>` 目录下，以 `Deployment` 为例：

$ pwd
    /Users/zhangjun/go/src/gitlab.4pd.io/pht3/aol/vendor/k8s.io/api/extensions/v1beta1
    
    $ ls -l
    total 1048
    -rw-r--r--  1 zhangjun  staff     642 Jan 22 15:16 doc.go
    -rw-r--r--  1 zhangjun  staff  308747 Jan 22 15:16 generated.pb.go
    -rw-r--r--  1 zhangjun  staff   49734 Jan 22 15:16 generated.proto
    -rw-r--r--  1 zhangjun  staff    2042 Jan 22 15:16 register.go
    -rw-r--r--  1 zhangjun  staff   69022 Jan 23 22:30 types.go
    -rw-r--r--  1 zhangjun  staff   47996 Jan 22 15:16 types_swagger_doc_generated.go
    -rw-r--r--  1 zhangjun  staff   41555 Jan 22 15:16 zz_generated.deepcopy.go

可以暂时忽略无关的文件，我们主要分析 `types.go`、`zz_generated.deepcopy.go` 和 `register.go` 三个文件。

1.  types.go：定义本 `<group>/<version>` 下所有的资源类型和 codegen 注释；
2.  zz\_generated.deepcopy.go：`deepcopy-gen` 工具创建的、定义各资源类型 `DeepCopyObject()` 方法的文件；
3.  register.go：定义了 `AddToScheme()` 函数，用于将本 `<group>/<version>` 下的各资源类型注册到 Clientset 使用的 Scheme 对象中（[k8s.io/client-go/kubernetes/scheme/）；][k8s.io_client-go_kubernetes_scheme]
4.  对于自定义资源类型，需要在 doc.go 中添加注释 **// +groupName=<group\_name>**，否则后续自动生成的 fake clientset 的 Group 不对；

### types.go 文件 ###

该文件包含资源类型的 go struct 定义及 codegen 命令行工具使用的注释：

// 来源于：k8s.io/api/extensions/v1beta1/types.go
    
    // +genclient
    // +genclient:method=GetScale,verb=get,subresource=scale,result=Scale
    // +genclient:method=UpdateScale,verb=update,subresource=scale,input=Scale,result=Scale
    // +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object
    
    // DEPRECATED - This group version of Deployment is deprecated by apps/v1beta2/Deployment. See the release notes for
    // more information.
    // Deployment enables declarative updates for Pods and ReplicaSets.
    type Deployment struct { 
    	metav1.TypeMeta `json:",inline"`
    	// Standard object metadata.
    	// +optional
    	metav1.ObjectMeta `json:"metadata,omitempty" protobuf:"bytes,1,opt,name=metadata"`
    
    	// Specification of the desired behavior of the Deployment.
    	// +optional
    	Spec DeploymentSpec `json:"spec,omitempty" protobuf:"bytes,2,opt,name=spec"`
    
    	// Most recently observed status of the Deployment.
    	// +optional
    	Status DeploymentStatus `json:"status,omitempty" protobuf:"bytes,3,opt,name=status"`
    }
    
    // DeploymentSpec is the specification of the desired behavior of the Deployment.
    type DeploymentSpec struct { 
    	Replicas *int32 `json:"replicas,omitempty" protobuf:"varint,1,opt,name=replicas"`
    	Selector *metav1.LabelSelector `json:"selector,omitempty" protobuf:"bytes,2,opt,name=selector"`
    	Template v1.PodTemplateSpec `json:"template" protobuf:"bytes,3,opt,name=template"`
    	Strategy DeploymentStrategy `json:"strategy,omitempty" patchStrategy:"retainKeys" protobuf:"bytes,4,opt,name=strategy"`
    	MinReadySeconds int32 `json:"minReadySeconds,omitempty" protobuf:"varint,5,opt,name=minReadySeconds"`
    	RevisionHistoryLimit *int32 `json:"revisionHistoryLimit,omitempty" protobuf:"varint,6,opt,name=revisionHistoryLimit"`
    	Paused bool `json:"paused,omitempty" protobuf:"varint,7,opt,name=paused"`
    	RollbackTo *RollbackConfig `json:"rollbackTo,omitempty" protobuf:"bytes,8,opt,name=rollbackTo"`
    	ProgressDeadlineSeconds *int32 `json:"progressDeadlineSeconds,omitempty" protobuf:"varint,9,opt,name=progressDeadlineSeconds"`
    }

### zz\_generated.deepcopy.go 文件 ###

所有注册到 Scheme 的资源类型都要实现 `runtime.Object` 接口：

// 来源于：k8s.io/apimachinery/pkg/runtime/interfaces.go
    type Object interface { 
    	GetObjectKind() schema.ObjectKind
    	DeepCopyObject() Object
    }

K8S 各资源类型的 go struct 定义都嵌入了 `metav1.TypeMeta` 类型，而该类型实现了 `GetObjectKind()` 方法，故各资源类型只需要实现 `DeepCopyObject()` 方法。

我们不需要手动为各资源类型定义 `DeepCopyObject()` 方法，而是使用 `deepcopy-gen` 工具命令统一、自动地生成该方法。

deepcopy-gen 工具读取 `types.go` 文件中的 `+k8s:deepcopy-gen` 注释，如：

// +k8s:deepcopy-gen:interfaces=k8s.io/apimachinery/pkg/runtime.Object

然后将生成的结果保存到 `zz_generated.deepcopy.go` 文件。

以 `Deployment` 类型为例：

// 来源于：k8s.io/api/extensions/v1beta1/zz_generated.deepcopy.go
    // DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new Deployment.
    func (in *Deployment) DeepCopy() *Deployment { 
    	if in == nil { 
    		return nil
    	}
    	out := new(Deployment)
    	in.DeepCopyInto(out)
    	return out
    }
    
    // DeepCopyObject is an autogenerated deepcopy function, copying the receiver, creating a new runtime.Object.
    func (in *Deployment) DeepCopyObject() runtime.Object { 
    	if c := in.DeepCopy(); c != nil { 
    		return c
    	}
    	return nil
    }

### register.go 文件 ###

使用 `deepcopy-gen` 工具命令统一、自动地为各资源类型生成 `DeepCopyObject()` 方法后，各资源类型就满足了 `runtime.Object` 接口，进而可以注册到 Scheme 中。

各 API Group/Version 目录下都有一个 `register.go` 文件，该文件对外提供的 `AddToScheme()` 方法用于将本 Group/Version 下的各资源类型注册到**传入**的 Scheme 对象中([k8s.io/client-go/kubernetes/scheme/register.go][k8s.io_client-go_kubernetes_scheme_register.go] 中创建该 Scheme 对象)，然后 Clientset 就可以使用它进行 Wired-data 和对象之间的转换了。

// 来源于：k8s.io/api/extensions/v1beta1/register.go
    // 本 package 的 Group 名称
    const GroupName = "extensions"
    
    // 注册时提供的 Group/Version 信息
    // 一个 Group 目录下，有可能有多个 Version 的子目录
    var SchemeGroupVersion = schema.GroupVersion{ Group: GroupName, Version: "v1beta1"}
    
    // Resource 实际就是资源类型的完整路径 <Group>/<Version>/<Plural>，如 extensions/v1beta1/deployments
    // Plural 是资源类型的复数形式
    func Resource(resource string) schema.GroupResource { 
    	return SchemeGroupVersion.WithResource(resource).GroupResource()
    }
    
    var (
    	SchemeBuilder      = runtime.NewSchemeBuilder(addKnownTypes)
    	localSchemeBuilder = &SchemeBuilder
    	// 对外暴露的 AddToScheme() 方法用于注册该 Group/Verion 下的所有资源类型
    	AddToScheme        = localSchemeBuilder.AddToScheme
    )
    
    // 将本 Group/Version 下的所有资源类型注册到传入的 scheme
    func addKnownTypes(scheme *runtime.Scheme) error { 
    	scheme.AddKnownTypes(SchemeGroupVersion,
    		&Deployment{ },
    		&DeploymentList{ },
    		...
    	)
    	// Add the watch version that applies
    	metav1.AddToGroupVersion(scheme, SchemeGroupVersion)
    	return nil
    }

## 注册所有内置资源类型到 Scheme 对象 ##

需要将 `k8s.io/api/<group>/<version>` 目录下的各资源类型注册到**全局 Scheme 对象**，这样 Clienset 才能识别和使用它们。

client-go 的 `scheme package`（[k8s.io/client-go/kubernetes/scheme/）定义了这个全局][k8s.io_client-go_kubernetes_scheme 1] `Scheme` 对象，并将各 `k8s.io/api/<Group>/<Version>` 目录下的资源类型注册到它上面。

Scheme 对象还被用于创建另外两个外部对象：

1.  对资源类型对象进行编解码(序列化/反序列化)的工厂对象 `Codecs`，后续使用它配置 `rest.Config.NegotiatedSerializer`；
2.  参数编解码对象 `ParameterCodec`，后续调用 RestFul 的方法时使用，如 `VersionedParams(&options, scheme.ParameterCodec)`。

// 来源于 k8s.io/client-go/kubernetes/scheme/register.go
    // 新建一个 Scheme，后续所有 K8S 类型均添加到该 Scheme；
    var Scheme = runtime.NewScheme()
    // 为 Scheme 中的所有类型创建一个编解码工厂；
    var Codecs = serializer.NewCodecFactory(Scheme)
    // 为 Scheme 中的所有类型创建一个参数编解码工厂
    var ParameterCodec = runtime.NewParameterCodec(Scheme)
    
    // 将各 `k8s.io/api/<Group>/<Version>` 目录下的资源类型的 AddToScheme() 方法注册到 SchemeBuilder 中
    var localSchemeBuilder = runtime.SchemeBuilder{ 
        ...
    	extensionsv1beta1.AddToScheme,
        ...
    }
    var AddToScheme = localSchemeBuilder.AddToScheme
    
    func init() { 
        v1.AddToGroupVersion(Scheme, schema.GroupVersion{ Version: "v1"})
    	// 调用 SchemeBuilder 中各资源对象的 AddToScheme() 方法，将它们注册到到 Scheme 对象。
    	utilruntime.Must(AddToScheme(Scheme))
    }

## 创建和使用 Kubernetes Clientset ##

经过前面的铺垫分析后，我们开始分析 Kubernetes Clientset 的创建过程。

先从使用者的角度看看如何创建和使用 Kubernetes Clientset：

var err error
    var config *rest.Config
    // 使用 ServiceAccount 创建集群配置
    if config, err = rest.InClusterConfig(); err != nil { 
    	// 使用 kubeConfig 指向的配置文件创建集群配置
    	if config, err = clientcmd.BuildConfigFromFlags("", *kubeConfig); err != nil { 
    		panic(err.Error())
    	}
    }
    
    // 创建 k8s clientset
    clientset, err = kubernetes.NewForConfig(config)
    if err != nil { 
    	panic(err.Error())
    }
    
    // 使用 clienset 创建一个 Deploy
    deploy, err := c.kubeclientset.ExtensionsV1beta1().Deployments(aolDeploy.ObjectMeta.Namespace).Create(myDeploy)

1.  使用 Kubeconfig 文件或 ServiceAccount 创建 Kubernetes 的 RestFul 配置参数；
2.  使用 Kubernetes 的 RestFul 配置参数，创建 Clientset；
3.  调用 Clientset 的方法对资源对象进行 CRUD；

## 创建支持所有资源类型的全局 Clientset ##

`k8s.io/client-go/kubernetes/clientset.go` 文件中创建的 Clientset 实际上是对各资源类型的 Clientset 做了一次封装：

1.  调用各资源类型的 NewForConfig() 函数创建对应的 Clientset；
2.  后续可以使用 Clientset.()，如 Clientset.ExtensionsV1beta1() 来调用具体资源类型的 Clientset；

// 来源于 k8s.io/client-go/kubernetes/clientset.go
    // 传入的 rest.Config 包含 apiserver 服务器和认证信息
    func NewForConfig(c *rest.Config) (*Clientset, error) { 
    	configShallowCopy := *c
        ...
        // 透传 rest.Config，调用具体分组和版本的资源类型的 ClientSet 构造函数
    	cs.extensionsV1beta1, err = extensionsv1beta1.NewForConfig(&configShallowCopy)
    	if err != nil { 
    		return nil, err
    	}
        ...
    	cs.DiscoveryClient, err = discovery.NewDiscoveryClientForConfig(&configShallowCopy)
    	if err != nil { 
    		return nil, err
    	}
    	return &cs, nil
    }
    
    // ExtensionsV1beta1 retrieves the ExtensionsV1beta1Client
    func (c *Clientset) ExtensionsV1beta1() extensionsv1beta1.ExtensionsV1beta1Interface { 
    	return c.extensionsV1beta1
    }

## 各资源类型的 Clientset ##

各资源类型的 Clientset 定义位于 `k8s.io/client-go/kubernetes/typed/<group>/<version>/<plug>_client.go` 文件中，如  
`k8s.io/client-go/kubernetes/typed/extensions/v1beta1/extensions_client.go`。

比较关键的是 `setConfigDefaults()` 函数，它负责为 Clientset 配置参数：

1.  资源对象的 GroupVersion；
2.  资源对象的 root path；
3.  对 wired data 进行编解码(序列化/反序列化)的 `NegotiatedSerializer`，使用的 `scheme.Codecs` 为前面介绍过的 `scheme package`；

RESTClient 根据配置的 root path 和 GroupVersion，构造 Resource 地址(格式为 `/apis/<group>/<version>/<name>`)。

// 来源于 k8s.io/client-go/kubernetes/typed/extensions/v1beta1/extensions_client.go
    // 传入的 rest.Config 包含 apiserver 服务器和认证信息
    func NewForConfig(c *rest.Config) (*ExtensionsV1beta1Client, error) { 
        config := *c
        // 为 rest.Config 设置资源对象相关的参数
    	if err := setConfigDefaults(&config); err != nil { 
    		return nil, err
        }
        // 创建 ExtensionsV1beta1 的 RestClient
    	client, err := rest.RESTClientFor(&config)
    	if err != nil { 
    		return nil, err
    	}
    	return &ExtensionsV1beta1Client{ client}, nil
    }
    
    func setConfigDefaults(config *rest.Config) error { 
        // 资源对象的 GroupVersion
    	gv := v1beta1.SchemeGroupVersion
        config.GroupVersion = &gv
        // 资源对象的 root path
        config.APIPath = "/apis"
        // 使用注册的资源类型 Schema 对请求和响应进行编解码
        // scheme 为前面分析过的 k8s.io/client-go/kubernetes/scheme package
    	config.NegotiatedSerializer = serializer.DirectCodecFactory{ CodecFactory: scheme.Codecs}
    
    	if config.UserAgent == "" { 
    		config.UserAgent = rest.DefaultKubernetesUserAgent()
    	}
    
    	return nil
    }
    
    func (c *ExtensionsV1beta1Client) Deployments(namespace string) DeploymentInterface { 
    	return newDeployments(c, namespace)
    }

## 各资源类型的 RestFul 方法 ##

使用各资源类型的 Clientset 创建特定资源类型的 RestFul 方法，参数的编解码工厂 `scheme.ParameterCodec` 来源于前面介绍的 `scheme package` 中。

// 来源于 k8s.io/client-go/kubernetes/typed/extensions/v1beta1/deployment.go
    // newDeployments returns a Deployments
    func newDeployments(c *ExtensionsV1beta1Client, namespace string) *deployments { 
    	return &deployments{ 
    		client: c.RESTClient(),
    		ns:     namespace,
    	}
    }
    
    // Get takes name of the deployment, and returns the corresponding deployment object, and an error if there is any.
    func (c *deployments) Get(name string, options v1.GetOptions) (result *v1beta1.Deployment, err error) { 
    	result = &v1beta1.Deployment{ }
    	// 发起实际的 RestFul 请求；
    	err = c.client.Get().
    		Namespace(c.ns).
    		Resource("deployments").
    		Name(name).
    		VersionedParams(&options, scheme.ParameterCodec).
    		Do().
    		Into(result)
    	return
    }

## 使用资源类型的 Clientset 创建 Informer 和 Lister ##

## 使用 codegen 工具生成资源类型的 Clientset、Informer 和 Lister ##

目录结构：

zhangjun:core zhangjun$ pwd
    /Users/zhangjun/go/src/gitlab.4pd.io/pht3/aol/pkg/apis/core/v1alpha1
    
    zhangjun:v1alpha1 zhangjun$ ls -l
    total 976
    -rw-r--r--  1 zhangjun  staff     643 Jan 28 21:14 doc.go
    -rw-r--r--  1 zhangjun  staff    1200 Jan 28 21:37 objectreference.go
    -rw-r--r--  1 zhangjun  staff    2741 Jan 28 21:39 register.go
    -rw-r--r--  1 zhangjun  staff  273720 Jan 28 21:40 types.go
    -rw-r--r--  1 zhangjun  staff  154116 Jan 28 21:41 zz_generated.deepcopy.go

在 `doc.go` 文件里添加 `// +k8s:deepcopy-gen=package`，否则后续不会为 `types.go` 中的类型生成 `DeepCopy()` 方法：

// 来源于 doc.go
    
    // +k8s:deepcopy-gen=package
    // +k8s:openapi-gen=true
    
    package v1alpha1

## 参考 ##

[Kubernetes Deep Dive: Code Generation for CustomResources][Kubernetes Deep Dive_ Code Generation for CustomResources]

[k8s.io_client-go_kubernetes_scheme]: http://k8s.io/client-go/kubernetes/scheme/%EF%BC%89%EF%BC%9B
[k8s.io_client-go_kubernetes_scheme_register.go]: http://k8s.io/client-go/kubernetes/scheme/register.go
[k8s.io_client-go_kubernetes_scheme 1]: http://k8s.io/client-go/kubernetes/scheme/%EF%BC%89%E5%AE%9A%E4%B9%89%E4%BA%86%E8%BF%99%E4%B8%AA%E5%85%A8%E5%B1%80
[Kubernetes Deep Dive_ Code Generation for CustomResources]: https://blog.openshift.com/kubernetes-deep-dive-code-generation-customresources/