kubernetes的API对象类型定义

在kubernetes里提供了非常多的API对象，它们被定义在k8s.io/api这个仓库中，这也是本章节命名为api的原因。Pod应该是最为基础的对象之一，在初学kubernetes时我相信大部分同学都写过类似下面的代码： 

apiVersion: v1
kind: Pod
metadata:
  name: myapp-pod
  labels:
    app: myapp
spec:
  containers:
  - name: myapp-container
    image: busybox
    command: ['sh', '-c', 'echo Hello Kubernetes! && sleep 3600']

“apiVersion”——“创建该对象所使用的 Kubernetes API 的版本”；
“kind”——“想要创建的对象的类型”；
“metadata”——“帮助识别对象唯一性的数据，包括一个 name 字符串、UID 和可选的 namespace。”

通过命令kubectl create -f xxx.yaml在kubernetes中创建了一个名字为myapp-pod的Pod对象(此处忽略namespace)。

用编程的角度分析上面的流程：在kubernetes中需要有一个Pod的类型，每次执行kubectl create -f xxx.yaml创建Pod对象的时候需要实例化Pod，并把xxx.yaml中的参数赋值到Pod对象中。

kubernetes中Pod类型是如何定义的：
 

type Pod struct {
    // metav1.TypeMeta, 对象的类型元数据信息。
    metav1.TypeMeta `json:",inline"`

    // metav1.ObjectMeta 定义对象的公共说明属性，包括对象名、命名空间、注释、标签等。
    metav1.ObjectMeta `json:"metadata,omitempty" protobuf:"bytes,1,opt,name=metadata"`

    // 从名字上看还是比较好理解的，就是Pod规格，最为代表性的就是CPU、内存的资源使用。它和xxx.yaml中
    // Spec用于定义资源的私有属性，这也是资源之间的区别所在
    // Spec是由用户定义的希望系统最终达到的状态，比如启动多少个replica、cpu和内存的限制等等。
    Spec PodSpec `json:"spec,omitempty" protobuf:"bytes,2,opt,name=spec"`

    // Status可标注Pod的状态，比如是运行还是挂起、Pod的IP、启动时间等等。
    // Status:系统的当前状态，由服务器去更新。
    Status PodStatus `json:"status,omitempty" protobuf:"bytes,3,opt,name=status"`

}

1.metav1.TypeMeta, 对象的类型元数据信息。

1.1 类型成员

定义了资源类型和api版本。

type TypeMeta struct {
    
	Kind string `json:"kind,omitempty" protobuf:"bytes,1,opt,name=kind"`

	APIVersion string `json:"apiVersion,omitempty" protobuf:"bytes,2,opt,name=apiVersion"`
}

1.2、相关接口

TypeMeta的相关接口主要实现了查看和设置资源类型和api版本的功能。

func (obj *TypeMeta) GetObjectKind() schema.ObjectKind { return obj }
//实现了schema.ObjectKind接口
type ObjectKind interface {
	// SetGroupVersionKind sets or clears the intended serialized kind of an object. Passing kind nil
	// should clear the current setting.
	SetGroupVersionKind(kind GroupVersionKind)
	// GroupVersionKind returns the stored group, version, and kind of an object, or nil if the object does
	// not expose or provide these fields.
	GroupVersionKind() GroupVersionKind
}

// SetGroupVersionKind satisfies the ObjectKind interface for all objects that embed TypeMeta
func (obj *TypeMeta) SetGroupVersionKind(gvk schema.GroupVersionKind) {
	obj.APIVersion, obj.Kind = gvk.ToAPIVersionAndKind()
}

// GroupVersionKind satisfies the ObjectKind interface for all objects that embed TypeMeta
func (obj *TypeMeta) GroupVersionKind() schema.GroupVersionKind {
	return schema.FromAPIVersionAndKind(obj.APIVersion, obj.Kind)
}

2.metav1.ObjectMeta

定义对象的公共说明属性，包括对象名、命名空间、注释、标签等。

2.1 类型成员

type ObjectMeta struct {
    // 对象的名字应该不用介绍了。
    Name string `json:"name,omitempty" protobuf:"bytes,1,opt,name=name"`
    // 如果Name为空，系统这为该对象生成一个唯一的名字。
    GenerateName string `json:"generateName,omitempty" protobuf:"bytes,2,opt,name=generateName"`
    // 命名空间，在平时学习、调试的时候很少用，但是在发布的时候会经常用。
    Namespace string `json:"namespace,omitempty" protobuf:"bytes,3,opt,name=namespace"`
    // 对象的URL，由系统生成。
    SelfLink string `json:"selfLink,omitempty" protobuf:"bytes,4,opt,name=selfLink"`
    // 对象的唯一ID，由系统生成。
    UID types.UID `json:"uid,omitempty" protobuf:"bytes,5,opt,name=uid,casttype=k8s.io/kubernetes/pkg/types.UID"`
    // 资源版本，这是一个非常有意思且变量，版本可以理解为对象在时间轴上的一个时间节点，代表着对象最后
    // 一次更新的时刻。如果说Name是在Namespace空间下唯一，那么ResourceVersion则是同名、同类型
    // 对象时间下唯一。因为同名对象在不同时间可能会更新、删除再添加，在比较两个对象谁比较新的情况
    // 非常有用，比如Watch。
    ResourceVersion string `json:"resourceVersion,omitempty" protobuf:"bytes,6,opt,name=resourceVersion"`
    Generation int64 `json:"generation,omitempty" protobuf:"varint,7,opt,name=generation"`
    // 对象创建时间，由系统生成。
    CreationTimestamp Time `json:"creationTimestamp,omitempty" protobuf:"bytes,8,opt,name=creationTimestamp"`
    // 对象删除时间，指针类型说明是可选的，当指针不为空的时候说明对象被删除了，也是由系统生成
    DeletionTimestamp *Time `json:"deletionTimestamp,omitempty" protobuf:"bytes,9,opt,name=deletionTimestamp"`
    // 对象被删除前允许优雅结束的时间，单位为秒。
    DeletionGracePeriodSeconds *int64 `json:"deletionGracePeriodSeconds,omitempty" protobuf:"varint,10,opt,name=deletionGracePeriodSeconds"`
    // 对象标签，这个是我们经常用的，不用多解释了
    Labels map[string]string `json:"labels,omitempty" protobuf:"bytes,11,rep,name=labels"`
    // 批注，这个和标签很像，但是用法不同，比如可以用来做配置。
    Annotations map[string]string `json:"annotations,omitempty" protobuf:"bytes,12,rep,name=annotations"`
    // 该对象依赖的对象类表，如果这些依赖对象全部被删除了，那么该对象也会被回收。如果该对象对象被
    // 某一controller管理，那么类表中有一条就是指向这个controller的。例如Deployment对象的
    // OwnerReferences有一条就是指向DeploymentController的。
    OwnerReferences []OwnerReference `json:"ownerReferences,omitempty" patchStrategy:"merge" patchMergeKey:"uid" protobuf:"bytes,13,rep,name=ownerReferences"`
    Finalizers []string `json:"finalizers,omitempty" patchStrategy:"merge" protobuf:"bytes,14,rep,name=finalizers"`
    ClusterName string `json:"clusterName,omitempty" protobuf:"bytes,15,opt,name=clusterName"`
    ManagedFields []ManagedFieldsEntry `json:"managedFields,omitempty" protobuf:"bytes,17,rep,name=managedFields"`
}

2.2、相关接口

metav1.ObjectMeta的相关接口主要是对资源公共属性的查看和设置。ObjectMeta实现了metav1.object和ObjectMetaAccessor两个interface，而kubernetes所有单体对象都继承了ObjectMeta，那么所有的API对象就都实现了metav1.object和ObjectMetaAccessor。metav1.Object是对API对象公共属性的抽象(interface)；
 

// TODO: move this, Object, List, and Type to a different package
type ObjectMetaAccessor interface {
	GetObjectMeta() Object
}

// Object lets you work with object metadata from any of the versioned or
// internal API objects. Attempting to set or retrieve a field on an object that does
// not support that field (Name, UID, Namespace on lists) will be a no-op and return
// a default value.
//注意此object为metav1.object
type Object interface {  
	GetNamespace() string
	SetNamespace(namespace string)
	GetName() string
	SetName(name string)
	GetGenerateName() string
	SetGenerateName(name string)
	GetUID() types.UID
	SetUID(uid types.UID)
	GetResourceVersion() string
	SetResourceVersion(version string)
	GetGeneration() int64
	SetGeneration(generation int64)
	GetSelfLink() string
	SetSelfLink(selfLink string)
	GetCreationTimestamp() Time
	SetCreationTimestamp(timestamp Time)
	GetDeletionTimestamp() *Time
	SetDeletionTimestamp(timestamp *Time)
	GetDeletionGracePeriodSeconds() *int64
	SetDeletionGracePeriodSeconds(*int64)
	GetLabels() map[string]string
	SetLabels(labels map[string]string)
	GetAnnotations() map[string]string
	SetAnnotations(annotations map[string]string)
	GetFinalizers() []string
	SetFinalizers(finalizers []string)
	GetOwnerReferences() []OwnerReference
	SetOwnerReferences([]OwnerReference)
	GetClusterName() string
	SetClusterName(clusterName string)
	GetManagedFields() []ManagedFieldsEntry
	SetManagedFields(managedFields []ManagedFieldsEntry)
}


// 代码源自k8s.io/apimachinery/pkg/apis/meta/v1/meta.go，GetObjectMeta是MetaAccessor
// 的接口函数，这个函数说明了ObjectMeta实现了MetaAccessor。
func (obj *ObjectMeta) GetObjectMeta() Object { return obj }
 
// 下面所有的函数是接口Object的ObjectMeta实现，可以看出来基本就是setter/getter方法。
func (meta *ObjectMeta) GetNamespace() string                { return meta.Namespace }
func (meta *ObjectMeta) SetNamespace(namespace string)       { meta.Namespace = namespace }
func (meta *ObjectMeta) GetName() string                     { return meta.Name }
func (meta *ObjectMeta) SetName(name string)                 { meta.Name = name }
func (meta *ObjectMeta) GetGenerateName() string             { return meta.GenerateName }
func (meta *ObjectMeta) SetGenerateName(generateName string) { meta.GenerateName = generateName }
func (meta *ObjectMeta) GetUID() types.UID                   { return meta.UID }
func (meta *ObjectMeta) SetUID(uid types.UID)                { meta.UID = uid }
func (meta *ObjectMeta) GetResourceVersion() string          { return meta.ResourceVersion }
func (meta *ObjectMeta) SetResourceVersion(version string)   { meta.ResourceVersion = version }
func (meta *ObjectMeta) GetGeneration() int64                { return meta.Generation }
func (meta *ObjectMeta) SetGeneration(generation int64)      { meta.Generation = generation }
func (meta *ObjectMeta) GetSelfLink() string                 { return meta.SelfLink }
func (meta *ObjectMeta) SetSelfLink(selfLink string)         { meta.SelfLink = selfLink }
func (meta *ObjectMeta) GetCreationTimestamp() Time          { return meta.CreationTimestamp }
func (meta *ObjectMeta) SetCreationTimestamp(creationTimestamp Time) {
    meta.CreationTimestamp = creationTimestamp
}
func (meta *ObjectMeta) GetDeletionTimestamp() *Time { return meta.DeletionTimestamp }
func (meta *ObjectMeta) SetDeletionTimestamp(deletionTimestamp *Time) {
    meta.DeletionTimestamp = deletionTimestamp
}
func (meta *ObjectMeta) GetDeletionGracePeriodSeconds() *int64 { return meta.DeletionGracePeriodSeconds }
func (meta *ObjectMeta) SetDeletionGracePeriodSeconds(deletionGracePeriodSeconds *int64) {
    meta.DeletionGracePeriodSeconds = deletionGracePeriodSeconds
}
func (meta *ObjectMeta) GetLabels() map[string]string                 { return meta.Labels }
func (meta *ObjectMeta) SetLabels(labels map[string]string)           { meta.Labels = labels }
func (meta *ObjectMeta) GetAnnotations() map[string]string            { return meta.Annotations }
func (meta *ObjectMeta) SetAnnotations(annotations map[string]string) { meta.Annotations = annotations }
func (meta *ObjectMeta) GetFinalizers() []string                      { return meta.Finalizers }
func (meta *ObjectMeta) SetFinalizers(finalizers []string)            { meta.Finalizers = finalizers }
func (meta *ObjectMeta) GetOwnerReferences() []OwnerReference         { return meta.OwnerReferences }
func (meta *ObjectMeta) SetOwnerReferences(references []OwnerReference) {
    meta.OwnerReferences = references
}
func (meta *ObjectMeta) GetClusterName() string                 { return meta.ClusterName }
func (meta *ObjectMeta) SetClusterName(clusterName string)      { meta.ClusterName = clusterName }
func (meta *ObjectMeta) GetManagedFields() []ManagedFieldsEntry { return meta.ManagedFields }
func (meta *ObjectMeta) SetManagedFields(managedFields []ManagedFieldsEntry) {
    meta.ManagedFields = managedFields
}

runtime.Object是所有API单体对象的根类(interface)；
schema.ObjectKind是对API对象类型的抽象(interface)；
metav1.Object是对API对象公共属性的抽象(interface)；
metav1.ListInterface是对API对象列表公共属性的抽象(interface)；
metav1.TypeMeta是schema.ObjectKind的一个实现，API对象类型继承之；
metav1.ObjectMeta是metav1.Object的一个实现，API对象类型继承之；
metav1.ListMeta是metav1.ListInterface的一个实现，API对象列表继承之；

资源的操作

资源通常有这几种操作：创建（Create），更新（Update），读取（Read），删除（Delete）。其中更新又分为替换（Replace）和打补丁（Patch），区别是替换是把整个spec替换掉，会有乐观锁保证读写安全；打补丁则是修改某些指定的字段，没有锁，最后一次写会成功。

参考：深入剖析kubernetes的API对象类型定义_进德的博客-CSDN博客

          ​​​​​​k8s API简介 - 简书

           K8S 剖析API对象类型_much efforts, much luck-CSDN博客