Xinzhao's Blog

Karmada Resource Interpreter Webhook 解析

2022-11-20T00:00:00Z

Karmada 介绍

在开始讲 Resource Interpreter Webhook 之前需要对 Karmada 的基础架构以及如何分发应用等有一定的了解，但那一部分在之前的博客中已经提到过了，所以这篇文章就不再赘述了，如果需要的话可以移步到 Kubernetes 多集群项目介绍了解。

一个例子：创建一个 nginx 应用

让我们先从一个最简单的例子开始，在 Karmada 中创建并分发一个 nginx 应用；首先是准备 nginx 的资源模板，这个就是原生的 K8s Deployment，不需要任何改变：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx
  labels:
    app: nginx
spec:
  replicas: 2
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - image: nginx
        name: nginx

再准备一个 PropagationPolicy，用来控制 nginx 分发到哪些集群：

apiVersion: policy.karmada.io/v1alpha1
kind: PropagationPolicy
metadata:
  name: nginx-propagation
spec:
  resourceSelectors:
    - apiVersion: apps/v1
      kind: Deployment
      name: nginx
  placement:
    clusterAffinity:
      clusterNames:
        - member1
        - member2

这里我们就直接将它分发到 member1 和 member2 集群。

member1 和 member2 集群分别有一个副本数为 2 的 nginx Deployment，所以该资源一共存在 4 个 Pod。

上面的例子非常简单，直接在 member 集群根据模板原封不动创建 Deployment 就行了，但是大家知道 Karmada 是支持一些更高级的副本数调度策略的，比如下面这个例子：

replicaScheduling:
  replicaDivisionPreference: Weighted
  replicaSchedulingType: Divided
  weightPreference:
    staticWeightList:
      - targetCluster:
          clusterNames:
            - member1
        weight: 1
      - targetCluster:
          clusterNames:
            - member2
        weight: 1

应用了该规则之后，会涉及到针对每个集群上资源副本数的动态调整，之后 Karmada 在 member 集群创建 Deployment 的时候就需要增加一个修改副本数的步骤。

针对 Deployment 这类 K8s 核心资源，因为其结构是确定的，我们可以直接编写修改其副本数的代码，但是如果我有一个功能类似 Deployment 的 CRD 呢？我也需要副本数调度，Karmada 能正确地修改它的副本数吗？答案是否定的，也正因此，Karmada 引入了一个新的特性来使其能深度支持自定义资源（CRD）。

Resource Interpreter Webhook

为了解决上面提到的问题，Karmada 引入了 Resource Interpreter Webhook，通过干预从 ResourceTemplate 到 ResourceBinding 到 Work 到 Resource 的这几个阶段来实现完整的自定义资源分发能力：

从一个阶段到另一个都会经过我们预定义的一个或多个接口，我们会在这些步骤中实现修改副本数等操作；用户需要增加一个单独的实现了对应接口的 webhook server，Karmada 会在执行到相应步骤时通过配置去调用该 server 来完成操作。

下面我们将选四个具有代表性的 hook 点来逐一介绍，接下来都使用以下 CRD 作为示例：

// Workload is a simple Deployment.
type Workload struct {
	metav1.TypeMeta   `json:",inline"`
	metav1.ObjectMeta `json:"metadata,omitempty"`

	// Spec represents the specification of the desired behavior.
	// +required
	Spec WorkloadSpec `json:"spec"`

	// Status represents most recently observed status of the Workload.
	// +optional
	Status WorkloadStatus `json:"status,omitempty"`
}

// WorkloadSpec is the specification of the desired behavior of the Workload.
type WorkloadSpec struct {
	// Number of desired pods. This is a pointer to distinguish between explicit
	// zero and not specified. Defaults to 1.
	// +optional
	Replicas *int32 `json:"replicas,omitempty"`

	// Template describes the pods that will be created.
	Template corev1.PodTemplateSpec `json:"template" protobuf:"bytes,3,opt,name=template"`

	// Paused indicates that the deployment is paused.
	// Note: both user and controllers might set this field.
	// +optional
	Paused bool `json:"paused,omitempty"`
}

// WorkloadStatus represents most recently observed status of the Workload.
type WorkloadStatus struct {
	// ReadyReplicas represents the total number of ready pods targeted by this Workload.
	// +optional
	ReadyReplicas int32 `json:"readyReplicas,omitempty"`
}

它和 Deployment 很像，我们用来演示 Karmada 如何支持这类资源来进行副本数调度等高级特性。

InterpretReplica

该 hook 点发生在从 ResourceTemplate 到 ResourceBinding 这个过程中，针对有 replica 功能的资源对象，比如类似 Deployment 的自定义资源，实现该接口来告诉 Karmada 对应资源的副本数。

apiVersion: workload.example.io/v1alpha1
kind: Workload
metadata:
  name: nginx
  labels:
    app: nginx
spec:
  replicas: 3
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
        - image: nginx
          name: nginx

针对我们示例的 Workload 资源，实现方式也非常简单，直接在 webhook server 中返回副本数的值即可：

func (e *workloadInterpreter) responseWithExploreReplica(workload *workloadv1alpha1.Workload) interpreter.Response {
	res := interpreter.Succeeded("")
	res.Replicas = workload.Spec.Replicas
	return res
}

注：所有的示例均来自 Karmada 官方文档，可以通过文章最后的参考链接来查看完整的示例和代码。

ReviseReplica

该 hook 点发生在从 ResourceBinding 到 Work 这个过程中，针对有 replica 功能的资源对象，需要按照 Karmada 发送的 request 来修改对象的副本数。Karmada 会通过调度策略把每个集群需要的副本数计算好，你需要做的只是把最后计算好的值赋给你的 CR 对象（因为 Karmada 并不知道该 CRD 的结构）：

func (e *workloadInterpreter) responseWithExploreReviseReplica(workload *workloadv1alpha1.Workload, req interpreter.Request) interpreter.Response {
	wantedWorkload := workload.DeepCopy()
	wantedWorkload.Spec.Replicas = req.DesiredReplicas
	marshaledBytes, err := json.Marshal(wantedWorkload)
	if err != nil {
		return interpreter.Errored(http.StatusInternalServerError, err)
	}
	return interpreter.PatchResponseFromRaw(req.Object.Raw, marshaledBytes)
}

核心代码也只有赋值那一行。

Workload 实现副本数调度

回到我们最初的那个问题，在了解了 InterpretReplica 和 ReviseReplica 两个 hook 点之后，就能够实现自定义资源按副本数调度了，实现 InterpretReplica hook 点以告知 Karmada 该资源的副本总数，实现 ReviseReplica hook 点来修改对象的副本数，再配置一个 PropagationPolicy 就可以了，配置方法和 Deployment 等资源一样：

apiVersion: policy.karmada.io/v1alpha1
kind: PropagationPolicy
metadata:
  name: nginx-workload-propagation
spec:
  resourceSelectors:
    - apiVersion: workload.example.io/v1alpha1
      kind: Workload
      name: nginx
  placement:
    clusterAffinity:
      clusterNames:
        - member1
        - member2
    replicaScheduling:
      replicaDivisionPreference: Weighted
      replicaSchedulingType: Divided
      weightPreference:
        staticWeightList:
          - targetCluster:
              clusterNames:
                - member1
            weight: 2
          - targetCluster:
              clusterNames:
                - member2
            weight: 1

效果如下：

Retain

该 hook 点发生在从 Work 到 Resource 这个过程中，针对 spec 内容会在 member 集群单独更新的情况，可以通过该 hook 告知 Karmada 保留某些字段的内容。

apiVersion: workload.example.io/v1alpha1
kind: Workload
metadata:
  name: nginx
  labels:
    app: nginx
spec:
  replicas: 3
  paused: false

以 paused 为例，该字段的功能是暂停 workload，member 集群的 controller 会单独更新该字段，Retain hook 就是为了能更好地和 member 集群的 controller 协作，可以通过该 hook 来告知 Karmada 哪些字段是需要不用更新、需要保留的。

func (e *workloadInterpreter) responseWithExploreRetaining(desiredWorkload *workloadv1alpha1.Workload, req interpreter.Request) interpreter.Response {
	if req.ObservedObject == nil {
		err := fmt.Errorf("nil observedObject in exploreReview with operation type: %s", req.Operation)
		return interpreter.Errored(http.StatusBadRequest, err)
	}
	observerWorkload := &workloadv1alpha1.Workload{}
	err := e.decoder.DecodeRaw(*req.ObservedObject, observerWorkload)
	if err != nil {
		return interpreter.Errored(http.StatusBadRequest, err)
	}

	// Suppose we want to retain the `.spec.paused` field of the actual observed workload object in member cluster,
	// and prevent from being overwritten by karmada controller-plane.
	wantedWorkload := desiredWorkload.DeepCopy()
	wantedWorkload.Spec.Paused = observerWorkload.Spec.Paused
	marshaledBytes, err := json.Marshal(wantedWorkload)
	if err != nil {
		return interpreter.Errored(http.StatusInternalServerError, err)
	}
	return interpreter.PatchResponseFromRaw(req.Object.Raw, marshaledBytes)
}

核心代码只有一行，更新 wantedWorkload 的 Paused 字段为之前版本的内容。

AggregateStatus

该 hook 点发生在从 ResourceBinding 到 ResourceTemplate 这个过程中，针对需要将 status 信息聚合到 Resource Template 的资源类型，可通过实现该接口来更新 Resource Template 的 status 信息。

Karmada 会将各个集群 Resouce 的状态信息统一收集到 ResourceBinding 中：

AggregateStatus hook 需要做的事情就是将 ResourceBinding 中 status 信息更新到 Resource Template 中：

func (e *workloadInterpreter) responseWithExploreAggregateStatus(workload *workloadv1alpha1.Workload, req interpreter.Request) interpreter.Response {
	wantedWorkload := workload.DeepCopy()
	var readyReplicas int32
	for _, item := range req.AggregatedStatus {
		if item.Status == nil {
			continue
		}
		status := &workloadv1alpha1.WorkloadStatus{}
		if err := json.Unmarshal(item.Status.Raw, status); err != nil {
			return interpreter.Errored(http.StatusInternalServerError, err)
		}
		readyReplicas += status.ReadyReplicas
	}
	wantedWorkload.Status.ReadyReplicas = readyReplicas
	marshaledBytes, err := json.Marshal(wantedWorkload)
	if err != nil {
		return interpreter.Errored(http.StatusInternalServerError, err)
	}
	return interpreter.PatchResponseFromRaw(req.Object.Raw, marshaledBytes)
}

逻辑也非常简单，根据 ResourceBinding 中的 status 信息来计算（聚合）出该资源总的 status 信息再更新到 Resource Template 中；效果和 Deployment 类似，可以直接查询到该资源在所有集群汇总后的状态信息：

参考链接

Kubernetes 多集群项目介绍

2021-11-03T00:00:00Z

为什么要使用集群联邦

Kubernetes 从 1.8 版本起就声称单集群最多可支持 5000 个节点和 15 万个 Pod，实际上应该很少有公司会部署如此庞大的一个单集群，很多情况下因为各种各样的原因我们可能会部署多个集群，但是又想将它们统一起来管理，这时候就需要用到集群联邦（Federation）。

集群联邦的一些典型应用场景：

高可用：在多个集群上部署应用，可以最大限度地减少集群故障带来的影响
避免厂商锁定：可以将应用负载分布在多个厂商的集群上并在有需要时直接迁移到其它厂商
故障隔离：拥有多个小集群可能比单个大集群更利于故障隔离

Federation v1

最早的多集群项目，由 K8s 社区提出和维护。

Federation v1 在 K8s v1.3 左右就已经着手设计（Design Proposal），并在后面几个版本中发布了相关的组件与命令行工具（kubefed），用于帮助使用者快速建立联邦集群，并在 v1.6 时，进入了 Beta 阶段；但 Federation v1 在进入 Beta 后，就没有更进一步的发展，由于灵活性和 API 成熟度的问题，在 K8s v1.11 左右正式被弃用。

v1 的基本架构如上图，主要有三个组件：

Federation API Server：类似 K8s API Server，对外提供统一的资源管理入口，但只允许使用 Adapter 拓展支持的 K8s 资源
Controller Manager：提供多个集群间资源调度及状态同步，类似 kube-controller-manager
Etcd：储存 Federation 的资源

在 v1 版本中我们要创建一个联邦资源的大致步骤如下：把联邦的所有配置信息都写到资源对象 annotations 里，整个创建流程与 K8s 类似，将资源创建到 Federation API Server，之后 Federation Controller Manager 会根据 annotations 里面的配置将该资源创建到各子集群；下面是一个 ReplicaSet 的示例：

这种架构带来的主要问题有两个：

不够灵活，每当创建一种新资源都要新增 Adapter（提交代码再发版）；并且对象会携带许多 Federation 专属的 Annotation
缺少独立的 API 对象版本控制，例如 Deployment 在 Kubernetes 中是 GA，但在 Federation v1 中只是 Beta

Federation v2

有了 v1 版本的经验和教训之后，社区提出了新的集群联邦架构：Federation v2；Federation 项目的演进也可以参考 Kubernetes Federation Evolution 这篇文章。

v2 版本利用 CRD 实现了整体功能，通过定义多种自定义资源（CR），从而省掉了 v1 中的 API Server；v2 版本由两个组件构成：

admission-webhook 提供了准入控制
controller-manager 处理自定义资源以及协调不同集群间的状态

在 v2 版本中要创建一个联邦资源的大致流程如下：

将 Federated Resource 创建到 Host 集群的 API Server 中，之后 controller-manager 会介入将相应资源分发到不同的集群，分发的规则等都写在了这个 Federated Resource 对象里面。

在逻辑上，Federation v2 分为两个大部分：configuration（配置）和 propagation（分发）；configuration 主要包含两个配置：Cluster Configuration 和 Type Configuration。

Cluster Configuration

用来保存被联邦托管的集群的 API 认证信息，可通过 kubefedctl join/unjoin 来加入/删除集群，当成功加入时，会建立一个 KubeFedCluster CR 来存储集群相关信息，如 API Endpoint、CA Bundle 和 Token 等。后续 controller-manager 会使用这些信息来访问不同 Kubernetes 集群。

apiVersion: core.kubefed.io/v1beta1
kind: KubeFedCluster
metadata:
  creationTimestamp: "2019-10-24T08:05:38Z"
  generation: 1
  name: cluster1
  namespace: kube-federation-system
  resourceVersion: "647452"
  selfLink: /apis/core.kubefed.io/v1beta1/namespaces/kube-federation-system/kubefedclusters/cluster1
  uid: 4c5eb57f-5ed4-4cec-89f3-cfc062492ae0
spec:
  apiEndpoint: https://172.16.200.1:6443
  caBundle: LS....Qo=
  secretRef:
    name: cluster1-shb2x
status:
  conditions:
  - lastProbeTime: "2019-10-28T06:25:58Z"
    lastTransitionTime: "2019-10-28T05:13:47Z"
    message: /healthz responded with ok
    reason: ClusterReady
    status: "True"
    type: Ready
  region: ""

Type Configuration

定义了哪些 Kubernetes API 资源要被用于联邦管理；比如说想将 ConfigMap 资源通过联邦机制建立在不同集群上时，就必须先在 Host 集群中，通过 CRD 建立新资源 FederatedConfigMap，接着再建立名称为 configmaps 的 Type configuration（FederatedTypeConfig）资源，然后描述 ConfigMap 要被 FederatedConfigMap 所管理，这样 Kubefed controller-manager 才能知道如何建立 Federated 资源，一个示例如下：

apiVersion: core.kubefed.k8s.io/v1beta1
kind: FederatedTypeConfig
metadata:
  name: configmaps
  namespace: kube-federation-system
spec:
  federatedType:
    group: types.kubefed.k8s.io
    kind: FederatedConfigMap
    pluralName: federatedconfigmaps
    scope: Namespaced
    version: v1beta1
  propagation: Enabled
  targetType:
    kind: ConfigMap
    pluralName: configmaps
    scope: Namespaced
    version: v1

Federated Resource CRD

其中还有一个关键的 CRD：Federated Resource，如果想新增一种要被联邦托管的资源的话，就需要建立一个新的 FederatedXX 的 CRD，用来描述对应资源的结构和分发策略（需要被分发到哪些集群上）；Federated Resource CRD 主要包括三部分：

Templates 用于描述被联邦的资源
Placement 用来描述将被部署的集群，若没有配置，则不会分发到任何集群中
Overrides 允许对部分集群的部分资源进行覆写

一个示例如下：

apiVersion: types.kubefed.k8s.io/v1beta1
kind: FederatedDeployment
metadata:
  name: test-deployment
  namespace: test-namespace
spec:
  template: # 定义 Deployment 的所有內容，可理解成 Deployment 与 Pod 之间的关联。
    metadata:
      labels:
        app: nginx
    spec:
      ...
  placement:
    clusters:
    - name: cluster2
    - name: cluster1
  overrides:
  - clusterName: cluster2
    clusterOverrides:
    - path: spec.replicas
      value: 5

这些 FederatedXX CRD 可以通过 kubefedctl enable <target kubernetes API type> 来创建，也可以自己生成/编写对应的 CRD 再创建。

结合上面介绍了的 Cluster Configuration、Type Configuration 和 Federated Resource CRD，再来看 v2 版本的整体架构和相关概念就清晰很多了：

Scheduling

Kubefed 目前只能做到一些简单的集群间调度，即手工指定，对于手工指定的调度方式主要分为两部分，一是直接在资源中制定目的集群，二是通过 ReplicaSchedulingPreference 进行比例分配。

直接在资源中指定可以通过 clusters 指定一个 cluster 列表，或者通过 clusterSelector 来根据集群标签选择集群，不过有两点要注意：

如果 clusters 字段被指定，clusterSelector 将会被忽略
被选择的集群是平等的，该资源会在每个被选中的集群中部署一个无差别副本

spec:
  placement:
    clusters:
    - name: cluster2
    - name: cluster1
    clusterSelector:
      matchLabels:
        foo: bar

如果需要在多个集群间进行区别调度的话就需要引入 ReplicaSchedulingPreference 进行按比例的调度了：

apiVersion: scheduling.kubefed.io/v1alpha1
kind: ReplicaSchedulingPreference
metadata:
  name: test-deployment
  namespace: test-ns
spec:
  targetKind: FederatedDeployment
  totalReplicas: 9
  clusters:
    A:
      minReplicas: 4
      maxReplicas: 6
      weight: 1
    B:
      minReplicas: 4
      maxReplicas: 8
      weight: 2

totalReplicas 定义了总副本数，clusters 描述不同集群的最大/最小副本以及权重。

目前 ReplicaSchedulingPreference 只支持 deployments 和 replicasets 两种资源。

Karmada

Karmada 是由华为开源的多云容器编排项目，这个项目是 Kubernetes Federation v1 和 v2 的延续，一些基本概念继承自这两个版本。

Karmada 主要有三个组件：

Karmada API Server：本质就是一个普通的 K8s API Server，绑定了一个单独的 etcd 来存储那些要被联邦托管的资源
Karmada Controller Manager：多个 controller 的集合，监听 Karmada API Server 中的对象并与成员集群 API server 进行通信
Karmada Scheduler：提供高级的多集群调度策略

和 Federation v1 类似，我们下发一个资源也是要写入到 Karmada 自己的 API Server 中，之前 controller-manager 根据一些 policy 把资源下发到各个集群中；不过这个 API Server 是 K8s 原生的，所以支持任何资源，不会出现之前 Federation v1 版本中的问题，然后联邦托管资源的分发策略也是由一个单独的 CRD 来控制的，也不需要配置 v2 中的 Federated Resource CRD 和 Type Configure。

Karmada 的一些基本概念：

资源模板（Resource Template）：Karmada 使用 K8s 原生 API 定义作为资源模板，便于快速对接 K8s 生态工具链
分发策略（Propagation Policy）：Karmada 提供独立的策略 API，用来配置资源分发策略
差异化策略（Override Policy）：Karmada 提供独立的差异化 API，用来配置与集群相关的差异化配置，比如配置不同集群使用不同的镜像

Cluster

Cluster 资源记录的内容和 Federation v2 类似，就是访问被纳管集群的一些必要信息：API Endpoint、CA Bundle 和访问 Token。

spec:
  apiEndpoint: https://172.31.165.66:55428
  secretRef:
    name: member1
    namespace: karmada-cluster
  syncMode: Push

但是有一个不一样的点是，Karmada 的 Cluster 资源有两种 sync 模式：Push 和 Pull；Push 就是最普通、最常见的方式，host 集群的 Karmada 组件会负责同步并更新这类集群的状态；Pull 模式的 member 集群上会运行一个 karmada-agent 组件，这个组件会负责收集自己的状态并且更新 host 集群的相应的 Cluster 资源状态。

Propagation Policy

在 Karmada 中分发资源到 member 集群需要配置这个单独 PropagationPolicy CR；以下面的 nginx 应用为例，首先是 Resource Template，这个就是普通的 K8s Deployment：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx
  labels:
    app: nginx
spec:
  replicas: 2
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - image: nginx
        name: nginx

之后配置一个 PropagationPolicy 来控制这个 nginx Deployment 资源的分发策略即可，在下面的示例中，会将 nginx 应用按 1:1 的权重比分发到 member1 和 member2 集群中：

apiVersion: policy.karmada.io/v1alpha1
kind: PropagationPolicy
metadata:
  name: nginx-propagation
spec:
  resourceSelectors:
    - apiVersion: apps/v1
      kind: Deployment
      name: nginx
  placement:
    clusterAffinity:
      clusterNames:
        - member1
        - member2
    replicaScheduling:
      replicaDivisionPreference: Weighted
      replicaSchedulingType: Divided
      weightPreference:
        staticWeightList:
          - targetCluster:
              clusterNames:
                - member1
            weight: 1
          - targetCluster:
              clusterNames:
                - member2
            weight: 1

在 Karmada API Server 中创建这两个资源后，可以通过 Karmada API Server 查询到该资源的状态：

$ kubectl get deploy
NAME    READY   UP-TO-DATE   AVAILABLE   AGE
nginx   2/2     2            2           51s

但是注意，这并不代表应用运行在 Karmada API Server 所在的集群上，实际上这个集群上没有任何工作负载，只是存储了这些 Resource Template，实际的工作负载都运行在上面 PropagationPolicy 配置的 member1 和 member2 集群中，切换到 member1/member2 集群中可以看到：

$ kubectl get deploy
NAME    READY   UP-TO-DATE   AVAILABLE   AGE
nginx   1/1     1            1           6m26s

$ kubectl get pod
NAME                     READY   STATUS    RESTARTS   AGE
nginx-6799fc88d8-7cgfz   1/1     Running   0          6m29s

分发策略除了上面最普通的指定集群名称外也支持 LabelSelector、FieldSelector 和 ExcludeClusters，如果这几个筛选项都设置了，那只有全部条件都满足的集群才会被筛选出来；除了集群亲和性，还支持 SpreadConstraints：对集群动态分组，按 region、zone 和 provider 等分组，可以将应用只分发到某类集群中。

针对有 replicas 的资源（比如原生的 Deployment 和 StatefulSet），支持在分发资源到不同集群的时候按要求更新这个副本数，比如 member1 集群上的 nginx 应用我希望有 2 个副本，member2 上的只希望有 1 个副本；策略有很多，首先是 ReplicaSchedulingType，有两个可选值：

Duplicated：每个候选成员集群的副本数都是一样的，从原本资源那里面复制过来的，和不设置 ReplicaSchedulingStrategy 的效果是一样的
Divided：根据有效的候选成员集群的数量，将副本分成若干部分，每个集群的副本数由 ReplicaDivisionPreference 决定

而这个 ReplicaDivisionPreference 又有两个可选值：

Aggregated：在考虑集群可用资源的情况下，将这些副本调度到尽量少的集群上，如果一个集群就能容纳所有副本，那只会调度到这一个集群上，其它集群上也会存在相应的资源，不过副本数是 0
Weighted：根据 WeightPreference 来划分副本数，这个 WeightPreference 就很简单了，直接指定每个集群的权重是多少

完整和详细的结构可以参考 Placement 的 API 定义。

Override Policy

Override Policy 就很简单了，通过增加 OverridePolicy 这个 CR 来配置不同集群的差异化配置，直接看一个例子：

apiVersion: policy.karmada.io/v1alpha1
kind: OverridePolicy
metadata:
  name: example-override
  namespace: default
spec:
  resourceSelectors:
    - apiVersion: apps/v1
      kind: Deployment
      name: nginx
  targetCluster:
    clusterNames:
      - member1
    labelSelector:
      matchLabels:
        failuredomain.kubernetes.io/region: dc1
  overriders:
    plaintext:
      - path: /spec/template/spec/containers/0/image
        operator: replace
        value: 'dc-1.registry.io/nginx:1.17.0-alpine'
      - path: /metadata/annotations
        operator: add
        value:
          foo: bar

Demo

最后看一个 Karmada 官方的例子：

参考链接

Kubernetes 组件单元测试指南

2021-07-15T00:00:00Z

前言

单元测试相关概念和基础内容这里不过多介绍，可以参考 go 官方的一些指南和网上的其它资料：

针对需要操作 k8s 的组件，单测的关键在于如何在单测的函数中构造一个 k8s 集群出来供业务函数对相应资源进行 CRUD，构造 k8s 集群的大致思路主要分为两类：使用 fake client 构造一个假的和在单测的过程中构造一个真的、轻量级的 k8s 集群；下面将逐一介绍这两种方法。

注：根据不同的测试对象，选择合适的、能达到测试目的方法即可，不必强行使用某一种方法

使用 fake client

fake client 基本只能用来 CRUD 各种资源（但其实这能覆盖到大部分场景了），一些其它的操作比如触发 informer 的 callback 事件等它是实现不了的，所以如果测试代码也想覆盖这类场景，需要使用下面的构造真正集群的方法；使用 fake client 测试步骤大致如下：

构造测试数据
- 即各种测试 case 中需要的（原生和自定义）资源对象
使用上面的测试数据生成 fake client
- 把这些测试对象 append 到 fake client 中
替换业务函数使用的 client 为 fake client
- 这个具体看业务函数是怎么实现的，怎么获取 k8s client 的

fake client 可以再细分成下面两类：

原生 client

指原生的 client-go 和使用 code-generator 生成的各 CR 的 typed client，这些 client 都提供了相应的 fake client 方法，fake client 很好构造，只用一个函数，把测试需要用到的对象都加进去就行：

client := fake.NewSimpleClientset(objects...)

一个简单示例如下，首先业务函数定义如下：

// Add adds or updates the given Event object.
func Add(kubeClient kubernetes.Interface, eventObj *corev1.Event) error {
	...
}

我需要测试的场景就两种：增加一个事件和更新已有的事件，针对这两个场景构造测试数据：

tests := []struct {
	name             string
	objects          []runtime.Object
	event            *corev1.Event
	isErr            bool
	wantedEventCount int32
}{
	{
		name:             "exist test",
		objects:          []runtime.Object{test.GetEvent()},
		event:            test.GetEvent(),
		isErr:            false,
		wantedEventCount: 1,
	},
	{
		name:             "not exist test",
		event:            test.GetEvent(),
		isErr:            false,
		wantedEventCount: 2,
	},
}

根据 case 的测试数据生成 fake client 并执行测试：

for _, tt := range tests {
	t.Run(tt.name, func(t *testing.T) {
		// 生成 fake client，把需要 CRUD 的资源加入进去
		client := fake.NewSimpleClientset(tt.objects...)

		// 执行函数
		err := Add(client, tt.event)
		if tt.isErr != (err != nil) {
			t.Errorf("%s Add() unexpected error: %v", tt.name, err)
		}

		// 校验结果是否符合预期
		eventObj, err := client.CoreV1().Events(tt.event.Namespace).Get(context.TODO(), tt.event.Name, metav1.GetOptions{})
		if err != nil {
			t.Errorf("%s unexpected error: %v", tt.name, err)
		}
		if eventObj.Count != tt.wantedEventCount {
			t.Errorf("%s event Count = %d, want %d", tt.name, eventObj.Count, tt.wantedEventCount)
		}
	})
}

注：测试函数不一定非得像示例这样写，重点了解下流程和构造 fake client 的方法即可

针对 controller 的测试，如果你有用到 lister 的话，还需要往对应资源的 informer 中增加需要的资源，这样业务代码里面 lister 才能读到相应的资源，简单示例如下：

// 创建 fake client
f.client = fake.NewSimpleClientset(f.objects...)

// 创建基于 fake client 的 informer
informer := informers.NewSharedInformerFactory(f.client, 0)

// 往 informer indexer 中添加对应的资源对象
for _, s := range f.storageClasses {
	informer.Native().Storage().V1().StorageClasses().Informer().GetIndexer().Add(s)
}

之后也是替换 client 和 informer 再运行测试即可。

generic client

指 controller-runtime 提供的 generic client，和上面的 typed client 不同的是，该 client 是一个通用的 client，可用于 CRUD 任何资源，测试方法基本和上面一样，只是构造 fake client 方法稍有不同，其它流程都一样，下面就只介绍构造 fake client 的方法，其它的内容就不再赘述了。

构造 generic client 的 fake client 的方法最大的一个不同点是它需要包含要 CRUD 的所有资源的 scheme：

// 配置 scheme 和需要添加的 objects
client := fake.NewClientBuilder().WithScheme(scheme.Scheme).WithObjects(objs...).Build()

scheme 的一般构造方法如下：

var (
	// Scheme contains all types of custom clientset and kubernetes client-go clientset
	Scheme = runtime.NewScheme()
)

func init() {
	// 添加你需要的资源的 scheme
	_ = clientgoscheme.AddToScheme(Scheme)
	_ = cosscheme.AddToScheme(Scheme)
	_ = apiextensionsv1.AddToScheme(Scheme)
}

构造轻量级集群

针对使用 fake client 不能覆盖的场景可使用这种方法进行测试，在单元测试中启动一个真实集群一般使用 controller-runtime 提供的 envtest 库，非常方便，由于是启动了一个真实的集群，该方法适用于任何 client。

测试步骤大致如下：

准备集群相关配置并启动集群
- 一般不需要额外配置，一个函数即可启动，如果有想要预注册 CRD 等才需要配置，配置项较多，可以参考 https://github.com/kubernetes-sigs/controller-runtime/blob/master/pkg/envtest/server.go#L105
使用上面创建的集群的 kube config 来生成各种 client
创建测试数据（如果需要的话）
进行测试，完成后销毁集群

启动集群方法如下：

// 生成 env，这里面有很多配置项，可以根据需要配置
testEnv := &envtest.Environment{}

// 启动环境，返回值是环境的 rest.Config，可用于生成各 kube client
config, err := testEnv.Start()
if err != nil {
	t.Fatal(err)
}

// 销毁集群
testEnv.Stop()

注意，该方法需要提前安装 kubebuilder，它依赖 kubebuilder 包提供的 apiserver 那几个 binary 文件，本地的话自己下载安装就好了，如果是 CI 环境需要的话，可以在基础镜像里面增加这些文件，一个示例：

RUN mkdir -p /usr/local && \
	wget https://go.kubebuilder.io/dl/2.3.1/linux/amd64 && \
	tar xvf amd64 && \
	mv kubebuilder_2.3.1_linux_amd64 /usr/local/kubebuilder && \
	rm amd64

下面是针对普通 client 的一个简单示例，业务函数定义如下：

// Create creates the given CRD objects or updates them if these objects already exist in the cluster.
func Create(client clientset.Interface, crds ...*apiextensionsv1.CustomResourceDefinition) error {
	...
}

测试准备：

// 启动测试集群
testEnv := &envtest.Environment{}
config, err := testEnv.Start()
if err != nil {
	t.Fatal(err)
}
defer testEnv.Stop()

// 生成需要的 apiextension client
apiextensionClient, _ := apiextensionsclient.NewForConfig(config)

之后再使用上面的 apiextensionClient 去执行测试即可。

针对 generic client 的一个简单示例如下：

// 启动测试集群
testEnv := &envtest.Environment{}
config, err := testEnv.Start()
if err != nil {
	t.Fatal(err)
}
defer testEnv.Stop()

// 生成 generic client
cli, err := client.New(config, client.Options{
	Scheme: scheme,
})
if err != nil {
	t.Fatal(err)
}

// 准备测试数据
sc1 := test.GetStorageClass()
sc1.Name = "sc1"
sc1.Provisioner = "example.com/test"
// 创建测试数据
if err := cli.Create(context.TODO(), sc1); err != nil {
	t.Fatal(err)
}

// 开始执行测试...

常用场景对比

	fake client	真实集群
资源 CRUD	支持	支持
使用 lister	支持，需要额外处理	支持，无需额外处理
informer 事件	不支持，无法触发	支持
运行依赖	无	需要安装 kubebuilder

fake client 使用简单，非常轻量级，执行速度快，但是它基本只能覆盖资源 CRUD 场景，其它操作的业务代码无法覆盖，还有一些场景能覆盖到但是需要一些额外的操作，稍微麻烦一点；构造真实集群完全能模拟组件运行在线上集群中的情况，几乎所有的业务代码只要想测都能覆盖到，但是执行速度较慢，对环境有特殊要求；选择哪种方案的一个简单判断方法是，用 fake client 测试能覆盖到的用 fake client，fake client 覆盖不到的再用构造真实集群的方法。

Kubernetes CRD v1 介绍

2021-07-06T00:00:00Z

前言

CRD API 在 Kubernetes v1.16 版本 GA 了，所以打算来聊一聊关于 CRD v1 版本的一些特性和一些常见的问题；关于 CRD 基础内容可能会一笔带过，不会涉及到太多，基础内容可以在 Kubernetes 官方文档上了解一下（后面参考链接有），可以更多地把这篇文章当作遇到问题时的速查手册。

CRD 是扩展 Kubernetes 最常见和最方便的方法，除了提供定义 custom resource（CR）的基本能力外，CRD 还提供了很多扩展能力，包括 schema、多版本、版本之间的 conversion、subresource 子资源等，本文主要介绍下面四部分的内容：

metadata: 定义了 CR 的基本信息，比如 API group 和名称
versions: 定义 CR 的版本信息
schema: 定义 CR 的结构和字段类型等信息
subresource: 定义 CR 的子资源信息

metadata

最基础但是最重要的部分，metadata 包含的主要内容是：

自定义资源 CR 的名称
该 CR 所属的 API group
scope: 资源是 Namespace 级别还是 Cluster 级别

下面是一个比较完整的例子（注释基本是从 K8s 官方文档上摘抄的，就不翻译了），假设我们要定义一种新的 VolumeSnapshot 资源：

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  # the name of this CR, must match the spec fields below, and be in the form: <plural>.<group>.
  name: volumesnapshots.example.com
spec:
  # group is the API group of the defined custom resource.
  #	The custom resources are served under `/apis/<group>/...`.
  #	Must match the name of the CustomResourceDefinition (in the form `<names.plural>.<group>`).
  group: example.com
  names:
    # kind is normally the CamelCased singular type. Your resource manifests use this.
    kind: VolumeSnapshot
    # listKind is the serialized kind of the list for this resource. Defaults to "`kind`List".
    listKind: VolumeSnapshotList
    # plural name to be used in the URL: /apis/<group>/<version>/<plural>
    plural: volumesnapshots
    # singular name to be used as an alias on the CLI and for display
    singular: volumesnapshot
    # shortNames allow shorter string to match your resource on the CLI
    # kubectl get volumesnapshot/vss
    shortNames:
    - vss
  # either Namespaced or Cluster
  scope: Namespaced

其中 group 必须是域名，不然创建的时候就会报下面的错：

The CustomResourceDefinition "volumesnapshots.test" is invalid: spec.group: Invalid value: "test": should be a domain with at least one dot

versions

定义了 CR 的版本信息，包括哪些版本是可用的，每个版本的结构信息，不同版本之间的转换策略等。

目前有两种版本转换的策略：

None: 默认的策略，只改 apiVersion，其它字段不管，旧版本有，但是新版本没有的字段的数据会直接丢失，同名但是结构不匹配的会报错
Webhook: 可以配置自定义的转换，API Server will call to an external webhook to do the conversion

还是再通过一个例子来看看整体结构：

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  ...
spec:
  ...
  # list of versions supported by this CustomResourceDefinition
  versions:
  - name: v1beta1
    served: true
    storage: true
    additionalPrinterColumns:
    - name: PVC
      type: string
      jsonPath: .spec.pvcName
    schema:
      ...
  # The conversion section is introduced in Kubernetes 1.13+ with a default value of
  # None conversion (strategy sub-field set to None).
  conversion:
    # None conversion assumes the same schema for all versions and only sets the apiVersion
    # field of custom resources to the proper value
    strategy: None

关于多版本的常见问题：

每个版本都可以通过 served 字段启用/禁用；有且仅有一个版本能被标记为存储版本（storage = true）

get served 为 false 的版本会直接报错：

Error from server (NotFound): Unable to list "example.com/v1, Resource=volumesnapshots": the server could not find the requested resource (get volumesnapshots.example.com)

创建的 CR 的版本最终均为 storage = true 的那个版本，创建以前的版本也会被转换成新版本的
如果存在以前的版本的 object，在更新这个 object 时会转换成 storage = true 的那个版本
转换均是通过 conversion 配置的 strategy 来进行的
当你获取资源时（比如使用 kubectl get），如果指定的版本与对象的存储时的版本不同，k8 会处理多版本之间的转换（by conversion），返回你指定的那个版本，但是这只是显示上的转换，实际上 etcd 中的数据还是老版本的，只有更新才会真正转换；如果 conversion 出问题的话，会报错：
```
Error from server: conversion webhook for example.com/v1beta1, Kind=VolumeSnapshot failed: Post  service "example-conversion-webhook-server" not found
```

schema

version 的一部分，定义了 CR 的结构信息，每个版本都有自己独立的 schema 结构，描述了 CR 有哪些字段，以及每个字段的类型等；schema 使用了 JSON Schema 标准，一个简单的例子如下：

apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  ...
spec:
  ...
  versions:
  - name: v1beta1
    served: true
    storage: true
    schema:
      openAPIV3Schema:
        type: object
        properties:
          spec:
            type: object
            properties:
              pvcName:
                type: string

该 CR 我们只定义了 spec 并且只有一个字段 pvcName，所以创建一个该 CR 的 YAML 文件如下：

apiVersion: example.com/v1beta1
kind: VolumeSnapshot
metadata:
  name: s1beta1
  namespace: default
spec:
  pvcName: pvc1

每个字段都可以设置默认值，这个字段是什么类型的，在 yaml 中 default 的值就要是什么类型的，比如我有下面三种类型的字段：

properties:
  type:
    type: array
    items:
      type: string
    default:
    - "test"
  name:
    type: string
    default: "test"
  size:
    type: number
    default: 1

字段还支持校验，比如 int 可以规定一个最大/最小值的范围，string 支持正则表达式校验和 enum 枚举。具体每种类型支持什么校验可以参考：JSON Schema Validation，一个例子：

properties:
  type:
    type: array
    items:
      type: string
    minItems: 2
  name:
    type: string
    pattern: '\\w+'
  size:
    type: number
    minimum: 1
    maximum: 10

schema 的一些常见问题：

所有字段必须在 schema 中定义，不然会报错：

error: error validating "snapshot-v1beta1.yaml": error validating data: ValidationError(VolumeSnapshot): unknown field "spec" in ...; if you choose to ignore these errors, turn validation off with --validate=false

如果想要存储没有事先定义的字段的话，可以给相应的父字段加上 x-kubernetes-preserve-unknown-fields: true 属性

定义了的字段可以不填，也可以配置 required 要求某些字段必填：

schema:
  openAPIV3Schema:
    type: object
    properties:
      spec:
        type: object
        properties:
          pvc:
            type: object
            required: ["size"]
            properties:
            ...

如果这个 spec.pvc.size 字段没填的话就会报错

如果关闭校验的话（kubectl create --validate=false ...），未定义的字段会被直接丢弃掉，不会存储
type 没有 map 类型，可以使用 type: object 配合 x-kubernetes-map-type 或者 x-kubernetes-preserve-unknown-fields 来充当 map 类型（允许任何字段）

subresource

支持两种类型的 subresource，一个是 Status subresource，一个是 Scale subresource，下面的例子中，status 和 scale 两种 subresource 都启用了：

# subresources describes the subresources for custom resources.
subresources:
  # status enables the status subresource.
  status: {}
  # scale enables the scale subresource.
  scale:
    # specReplicasPath defines the JSONPath inside of a custom resource that corresponds to Scale.Spec.Replicas.
    specReplicasPath: .spec.replicas
    # statusReplicasPath defines the JSONPath inside of a custom resource that corresponds to Scale.Status.Replicas.
    statusReplicasPath: .status.replicas
    # labelSelectorPath defines the JSONPath inside of a custom resource that corresponds to Scale.Status.Selector.
    labelSelectorPath: .status.labelSelector

status subresource

开启 status subresource 之后，整个 CR 的内容将被分为 spec 和 status 两部分，分别表示资源期望的状态和资源的实际状态，然后该资源的 API 会暴露一个新的 /status 接口，这个 CR 的创建/更新接口会校验整个内容（包括 status 的），但是 status 整个会被忽略，status 只能通过 /status 接口来更新，/status 接口只会更新/校验 status 的内容，其它的会被忽略。

针对 client-go，只要 type 定义了 Status 就会生成 UpdateStatus 方法：

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

// Snapshot is the snapshot object of the specified PVC.
type Snapshot struct {
	metav1.TypeMeta `json:",inline"`
	// Standard object's metadata.
	// More info: <https://git.k8s.io/community/contributors/devel/api-conventions.md#metadata>
	// +optional
	metav1.ObjectMeta `json:"metadata,omitempty"`

	Spec   SnapshotSpec   `json:"spec,omitempty"`
	Status SnapshotStatus `json:"status,omitempty"`
}

// SnapshotInterface has methods to work with Snapshot resources.
type SnapshotInterface interface {
	Create(*v1beta1.Snapshot) (*v1beta1.Snapshot, error)
	Update(*v1beta1.Snapshot) (*v1beta1.Snapshot, error)
	UpdateStatus(*v1beta1.Snapshot) (*v1beta1.Snapshot, error)
	...
}

// UpdateStatus was generated because the type contains a Status member.
// Add a +genclient:noStatus comment above the type to avoid generating UpdateStatus().
func (c *snapshots) UpdateStatus(snapshot *v1beta1.Snapshot) (result *v1beta1.Snapshot, err error) {
	result = &v1beta1.Snapshot{}
	err = c.client.Put().
		Namespace(c.ns).
		Resource("snapshots").
		Name(snapshot.Name).
		SubResource("status").
		Body(snapshot).
		Do().
		Into(result)
	return
}

scale subresource

和 status subresource 类似，启用之后也会暴露一个新的 /scale 接口，但是我基本没使用过这个，就不过多介绍了，可以看下官方的文档，scale subresource 启用之后还可以使用 kubectl scale 来单独控制资源的副本数量：

kubectl scale --replicas=5 crontabs/my-new-cron-object
crontabs "my-new-cron-object" scaled

kubectl get crontabs my-new-cron-object -o jsonpath='{.spec.replicas}'
5

参考链接

controller-runtime 介绍

2020-08-20T00:00:00Z

概述

controller-runtime 是 Kubebuilder 的子项目，提供了一系列用于构建 controller 的库；Kubebuilder 本身也是生成了大量的使用 controller-runtime 的模板代码。controller-runtime 中的几个基本概念：

Controller：字面意思，一个 controller。
Reconciler：提供 Reconcile 函数，Controller 的主要部分和入口函数，包含这个 controller 的所有业务逻辑（等同于普通 controller 中的 syncHandler 函数），用于使我们关注的 object 的实际状态逐渐向期望状态逼近。Reconciler 还有以下特点：
- 通常只针对一种类型的 object，不同类型的 object 使用单独的 controller。
- 通常不关心触发 Reconcile 函数的事件内容和类型；比如不管 ReplicaSet 是创建还是更新，ReplicaSet Reconciler 总是将集群中 Pod 的数量与 object 中设定的数量进行比较，再做出相应的操作。
Builder：基于一些配置，为 Reconciler 生成 Controller。
Manager：管理和启动 Controller，一个 Manager 可包含多个 Controller。

使用

下面以官方的一个简单例子来分步介绍怎么使用 controller-runtime 构建一个 controller：首先定义 Reconciler，其中包含 controller 的主要逻辑，然后使用 Builder 生成 Controller 并加入到 Manager 中，最后启动 Manager。

注：以 v0.5.0 版本为例，最新版 Reconcile 函数定义有变化

每一步的详细介绍如下：

Reconciler

介绍

Reconciler 的定义如下，仅包含一个 Reconcile 函数：

type Reconciler interface {
	// Reconciler performs a full reconciliation for the object referred to by the Request.
	// The Controller will requeue the Request to be processed again if an error is non-nil or
	// Result.Requeue is true, otherwise upon completion it will remove the work from the queue.
	Reconcile(Request) (Result, error)
}

Request 和 Result 定义如下：

// Request contains the information necessary to reconcile a Kubernetes object.  This includes the
// information to uniquely identify the object - its Name and Namespace.  It does NOT contain information about
// any specific Event or the object contents itself.
type Request struct {
	// NamespacedName is the name and namespace of the object to reconcile.
	types.NamespacedName
}

// Result contains the result of a Reconciler invocation.
type Result struct {
	// Requeue tells the Controller to requeue the reconcile key.  Defaults to false.
	Requeue bool

	// RequeueAfter if greater than 0, tells the Controller to requeue the reconcile key after the Duration.
	// Implies that Requeue is true, there is no need to set Requeue to true at the same time as RequeueAfter.
	RequeueAfter time.Duration
}

Request 包含本次 reconcile object 的 namespace 和 name，object 类型是生成 controller 时配置的，一个 Reconciler 仅能处理一种类型的 object；Result 基本不用关心，如果 Reconcile 返回 error 会自动 requeue。

使用示例

定义一个 ReplicaSetReconciler，其中包含一个由 controller-runtime 提供的一个 generic client，功能同普通的 kubernetes client，能获取到集群的所有资源：

// ReplicaSetReconciler is a simple ControllerManagedBy example implementation.
type ReplicaSetReconciler struct {
	client.Client
}

不过和普通 kubernetes client 不同的是，这个通用 client 是一个 client 就能 CRUD 所有类型的资源，非常方便和易于使用。

然后是实现业务逻辑：

// Implement the business logic:
// This function will be called when there is a change to a ReplicaSet or a Pod with an OwnerReference
// to a ReplicaSet.
//
// * Read the ReplicaSet
// * Read the Pods
// * Set a Label on the ReplicaSet with the Pod count
func (a *ReplicaSetReconciler) Reconcile(req reconcile.Request) (reconcile.Result, error) {
	// Read the ReplicaSet
	rs := &appsv1.ReplicaSet{}
	err := a.Get(context.TODO(), req.NamespacedName, rs)
	if err != nil {
		return reconcile.Result{}, err
	}

	// List the Pods matching the PodTemplate Labels
	pods := &corev1.PodList{}
	err = a.List(context.TODO(), client.InNamespace(req.Namespace).MatchingLabels(rs.Spec.Template.Labels), pods)
	if err != nil {
		return reconcile.Result{}, err
	}

	// Update the ReplicaSet
	rs.Labels["pod-count"] = fmt.Sprintf("%v", len(pods.Items))
	err = a.Update(context.TODO(), rs)
	if err != nil {
		return reconcile.Result{}, err
	}

	return reconcile.Result{}, nil
}

InjectClient 将 manager 真实的 client 赋给 ReplicaSetReconciler：

func (a *ReplicaSetReconciler) InjectClient(c client.Client) error {
	a.Client = c
	return nil
}

Builder 和 Manager

Builder 用来为 Reconciler 生成 Controller，Manager 用来管理和启动 Controller，直接用例子来介绍，首先生成一个 Manager：

mgr, err := manager.New(config, manager.Options{})
if err != nil {
	log.Error(err, "could not create manager")
	os.Exit(1)
}

其中 config 为 client-go 的 rest.Config。

为 ReplicaSetReconciler 生成 Controller 并加入到 Manager 中：

_, err = builder.
	ControllerManagedBy(mgr).  // Create the ControllerManagedBy
	For(&appsv1.ReplicaSet{}). // ReplicaSet is the Application API
	Owns(&corev1.Pod{}).       // ReplicaSet owns Pods created by it
	Build(&ReplicaSetReconciler{})
if err != nil {
	log.Error(err, "could not create controller")
	os.Exit(1)
}

其中 For 函数用于指定我们要 reconcile 的 object 类型，Owns 用来 watch 其 owner 是 reconcile object 类型的 object（Owns 可以指定多种类型），这两种类型 object 的增/删/改事件均会触发 Reconcile 函数。

最后启动 Manager，整个组件启动：

if err := mgr.Start(stopCh); err != nil {
	log.Error(err, "could not start manager")
	os.Exit(1)
}

单元测试

为普通的 controller 写单元测试主要还是依赖 client-go 提供的 fake client，将测试需要的各种 object append 到一个 fake client 中，使用这个 fake client 来完成测试，有用到 lister 的话需要手动往对应的 informer indexer 中添加相应的 object，示例：

// 创建 fake client
f.client = fake.NewSimpleClientset(f.objects...)

// 创建基于 fake client 的 informer
informer := informers.NewSharedInformerFactory(f.client, 1)

// 往 informer indexer 中添加 object
for _, s := range f.storageClasses {
	informer.Native().Storage().V1().StorageClasses().Informer().GetIndexer().Add(s)
}

controller-runtime 是使用了自己的 envtest 包在本地启动一个真正的 apiserver 和 etcd，然后连接这个 apiserver 进行测试，我们还是需要 fake objects，不过和 fake client 不同，这些 fake objects 是要创建到 controller-runtime 启动的 apiserver 中，如果是 CR 的话，还需要先往这个新的 apiserver 中注册 CRD。一个完整的示例：

func TestNodeLocalStorageReconciler(t *testing.T) {
	// 配置 testEnv，其中包含该项单测需要的 CRD 等
	testEnv := &envtest.Environment{
		CRDs: []runtime.Object{
			newNodeLocalStorageCRD(),
		},
	}

	// 启动测试环境（etcd 和 apiserver），返回该环境的 rest config
	config, err := testEnv.Start()
	if err != nil {
		t.Fatal(err)
	}
	defer testEnv.Stop()

	// 生成 controller-runtime 需要的 client
	c, err := client.New(config, client.Options{
		Scheme: scheme,
	})
	if err != nil {
		t.Fatal(err)
	}

	// 初始化 Reconciler
	nlsReconciler := &NodeLocalStorageReconciler{
		Client: c,
	}

	// 准备好测试数据
	nls1 := test.GetNodeLocalStorage()
	nls1.Name = "test"
	if err = c.Create(context.TODO(), nls1); err != nil {
		t.Fatal(err)
	}

	// test cases
	testCases := []struct {
		describe  string
		namespace string
		name      string
		isErr     bool
	}{
		{
			describe:  "normal test",
			namespace: "",
			name:      "test",
			isErr:     false,
		},
	}

	// 测试每个 case
	for _, testCase := range testCases {
		_, err := nlsReconciler.Reconcile(reconcile.Request{
			NamespacedName: types.NamespacedName{
				Namespace: testCase.namespace,
				Name:      testCase.name,
			},
		})
		if testCase.isErr != (err != nil) {
			t.Fatalf("%s unexpected error: %v", testCase.describe, err)
		}
	}
}

总结

controller-runtime 框架本身提供了很多库来帮助构建 controller，让整个流程变得简单，屏蔽了很多通用的细节，能够让构建 controller 整个过程变得更简单，感兴趣的同学可以在不同的场景和需求下都尝试一下；即便不使用 controller-runtime 我们也可以单独使用它的 generic client 和 envtest 等通用库。

单独说下使用 envtest 需要运行环境（你本地和 CI 等环境）安装 Kubebuilder 提供的一系列 bin 文件（主要是 etcd 和 kube-apiserver），本地的话自己下载就好了，如果是 CI 环境需要的话，可以在基础镜像里面增加这些文件，一个示例：

RUN mkdir -p /usr/local && \
	wget https://go.kubebuilder.io/dl/2.3.1/linux/amd64 && \
	tar xvf amd64 && \
	mv kubebuilder_2.3.1_linux_amd64 /usr/local/kubebuilder && \
	rm amd64

在使用 SharedInformerFactory 时一些很小但值得注意的问题

2020-05-11T00:00:00Z

近期在工作中被不同的同事问了一些类似的、关于 SharedInformerFactory 的问题，有些问题非常小，很细节，虽然小但是我觉得是值得注意的问题，所以打算总结分享一下。

不要使用 goroutine 来启动 SharedInformerFactory

我不是说用 goroutine 来启动就一定是错的，但是用 goroutine 来启动 SharedInformerFactory 没有意义，因为这个方法根本就不会 block，直接启动就好了，Start 方法的源代码：

// Start initializes all requested informers.
func (f *sharedInformerFactory) Start(stopCh <-chan struct{}) {
	f.lock.Lock()
	defer f.lock.Unlock()

	for informerType, informer := range f.informers {
		if !f.startedInformers[informerType] {
			go informer.Run(stopCh)
			f.startedInformers[informerType] = true
		}
	}
}

使用 goroutine 来启动还有另一个问题：它可能导致 WaitForCacheSync 不再起作用，WaitForCacheSync 方法必须要在 informer factory 完全启动（这个方法执行完成）之后再调用，不然它会拿到错误的已启动 informers 的数据，导致它并没有等待所有 informers 启动就返回结果了，看源代码：

// WaitForCacheSync waits for all started informers' cache were synced.
func (f *sharedInformerFactory) WaitForCacheSync(stopCh <-chan struct{}) map[reflect.Type]bool {
	informers := func() map[reflect.Type]cache.SharedIndexInformer {
		f.lock.Lock()
		defer f.lock.Unlock()

		informers := map[reflect.Type]cache.SharedIndexInformer{}
		for informerType, informer := range f.informers {
			if f.startedInformers[informerType] {
				informers[informerType] = informer
			}
		}
		return informers
	}()

	res := map[reflect.Type]bool{}
	for informType, informer := range informers {
		res[informType] = cache.WaitForCacheSync(stopCh, informer.HasSynced)
	}
	return res
}

WaitForCacheSync 需要从 f.startedInformers 中获取已启动 informers 的数据，而 f.startedInformers 是在执行 Start 方法时填充的，使用 goroutine 来启动 SharedInformerFactory 之后再正常 wait for sync 往往都是 WaitForCacheSync 函数先于 Start 方法执行，它会先拿到锁，等到它执行完了 Start 才会开始执行，导致该函数完全没有起到 wait 的效果；可以用下面的示例代码（可自行调整用 goroutine 来启动不同的方法）来看看效果：

package main

import (
	"fmt"
	"sync"
	"time"
)

type factory struct {
	lock sync.RWMutex
	data map[string]string
}

func (f *factory) method1() {
	f.lock.Lock()
	defer f.lock.Unlock()

	f.data["k1"] = "v1"
	f.data["k2"] = "v2"
}

func (f *factory) method2() {
	a := func() {
		f.lock.Lock()
		defer f.lock.Unlock()

		for k, v := range f.data {
			fmt.Println(k, v)
		}
	}
	a()
}

func main() {
	f := &factory{
		data: make(map[string]string),
	}
	f.method1()
	f.method2()
	time.Sleep(time.Second * 1)
}

Wrong	Correct
`go informerFactory.Start(stopCh) informerFactory.WaitForCacheSync(stopCh)`	`informerFactory.Start(stopCh) informerFactory.WaitForCacheSync(stopCh)`

正确启动 SharedInformerFactory

在调用 informerFactory.Start 方法之前，你必须保证直接或间接调用了你想使用的 informer 的 Informer() 方法，否则之后 Start 方法不会起作用，它不会启动任何东西；调用示例：

直接调用	间接调用
`informerFactory.Core().V1().Pods().Informer()`	`informerFactory.Core().V1().Pods().Lister()`

其中 Lister 方法会调用 Informer 方法，而 Informer 方法会调用 factory 的 InformerFor 方法，该方法会将当前 informer 数据写入到 factory 中，后续启动的时候会使用到：

// InternalInformerFor returns the SharedIndexInformer for obj using an internal
// client.
func (f *sharedInformerFactory) InformerFor(obj runtime.Object, newFunc internalinterfaces.NewInformerFunc) cache.SharedIndexInformer {
	f.lock.Lock()
	defer f.lock.Unlock()

	informerType := reflect.TypeOf(obj)
	informer, exists := f.informers[informerType]
	if exists {
		return informer
	}

	resyncPeriod, exists := f.customResync[informerType]
	if !exists {
		resyncPeriod = f.defaultResync
	}

	informer = newFunc(f.client, resyncPeriod)
	f.informers[informerType] = informer

	return informer
}

Wrong Correct

Wrong	Correct
`informerFactory := informers.NewSharedInformerFactory(kubeClient, 0) informerFactory.Start(stopch) podLister := informerFactory.Core().V1().Pods().Lister() ...`	`informerFactory := informers.NewSharedInformerFactory(kubeClient, 0) podLister := informerFactory.Core().V1().Pods().Lister() informerFactory.Start(stopch) ...`

informerFactory := informers.NewSharedInformerFactory(kubeClient, 0)
informerFactory.Start(stopch)
podLister := informerFactory.Core().V1().Pods().Lister()
...

informerFactory := informers.NewSharedInformerFactory(kubeClient, 0)
podLister := informerFactory.Core().V1().Pods().Lister()
informerFactory.Start(stopch)
...

上面错误的方法中，informerFactory 不会启动也不会缓存任何东西，podLister 会永远返回空结果。

在一些通用框架的场景下也可以使用 ForResource 方法来手动“注册”一个资源，它其实也是调用了对应资源的 Informer 方法：

type SharedInformerFactory interface {
	...
	ForResource(resource schema.GroupVersionResource) (GenericInformer, error)
}

// ForResource gives generic access to a shared informer of the matching type
func (f *sharedInformerFactory) ForResource(resource schema.GroupVersionResource) (GenericInformer, error) {
	switch resource {
	// Group=snapshot.storage.k8s.io, Version=v1beta1
	case v1beta1.SchemeGroupVersion.WithResource("volumesnapshots"):
		return &genericInformer{resource: resource.GroupResource(), informer: f.Snapshot().V1beta1().VolumeSnapshots().Informer()}, nil
	case v1beta1.SchemeGroupVersion.WithResource("volumesnapshotclasses"):
		return &genericInformer{resource: resource.GroupResource(), informer: f.Snapshot().V1beta1().VolumeSnapshotClasses().Informer()}, nil
	case v1beta1.SchemeGroupVersion.WithResource("volumesnapshotcontents"):
		return &genericInformer{resource: resource.GroupResource(), informer: f.Snapshot().V1beta1().VolumeSnapshotContents().Informer()}, nil

	}

	return nil, fmt.Errorf("no informer found for %v", resource)
}

使用 Ceph 做持久化存储的常见问题

2018-09-30T00:00:00Z

Ceph 是一个开源的分布式对象、块和文件存储系统。Kubernetes 支持 Ceph 的块存储（Ceph RBD）和文件存储（CephFS）作为 Kubernetes 的持久存储后端。

前言

Ceph 集群的安装过程这些就不过多阐述了，参照官网文档就行了，可以选择直接装在物理机上（我用的这种方式），也可以使用 Helm 来安装在 k8s 集群中，按需选择吧。

下面是一些安装参考文档：

安装 Ceph 集群常见问题

先说一下安装环境，参考上面的官网文档的步骤进行安装的，共 4 台服务器，1 台用来部署，其他 3 台用作 Ceph 的节点，所有服务器的操作系统都是 CentOS 7.5。

不要用 root 用户

官网文档明确指出了不要图方便就用 root 这种用户，极其不推荐。

节点数量

Ceph 默认需要 3 个 osd 节点，如果你机器数量不够可以使用下面的配置更改默认的设置：

osd pool default size = 2

关于 `.ssh/config` 文件

Host node1
   Hostname 192.168.21.50
   User c

Host name 要和机器的名称匹配。

顺便说一下，增加了这个文件之后还要更新一下 hosts 文件 vim /etc/hosts，把 host name 对应的 IP 地址写进去：

192.168.21.50 node1
...

ImportError: No module named pkg_resources

更新一下机器的 python 环境：

yum install gcc python-setuptools python-devel

easy_install pip

RuntimeError: NoSectionError: No section: 'ceph'

检查一下 yum 的配置文件 /etc/yum.repos.d/ 里面 ceph.repo 这个文件中有没有 ceph 这一段，没有的话检查一下这个目录下面应该有一个 ceph.repo.rpmnew 的文件，使用这个新的文件即可：

mv ceph.repo ceph.repo.old

mv ceph.repo.rpmnew ceph.repo

使用 Ceph 的常见问题

Provisioner

Kubernetes 自带 Ceph RBD 的 internal provisioner，可以配置动态存储提供（Dynamic Volume Provisioning），CephFS 则需要外置的 provisioner。

Kubernetes Storage Class 支持的 Provisioner 列表可以参考官网文档。

Error creating rbd image: executable file not found in $PATH

所有 k8s 节点的物理机上都要安装 ceph-common 这个包（yum install ceph-common），这个 client 的版本要和 Ceph 集群版本一致。

feature set mismatch missing 400000000000000

顺便说一下，如果你遇到了 timeout expired waiting for volumes to attach/mount for pod 这个错误，很可能也是下面的原因

原因是 Linux 内核版本和 Ceph 当前版本支持的不匹配（内核版本太低了，不支持当前版本的 Ceph 需要的一些特性），可以使用下面的命令来使 Ceph 兼容当前的内核版本（这么说好像不太对，大概是这个意思）：

ceph osd crush tunables hammer

hammer 是对应内核支持的 Ceph 版本，对照表如下：

> TUNABLE          RELEASE   CEPH_VERSION  KERNEL
> CRUSH_TUNABLES   argonaut  v0.48.1       v3.6
> CRUSH_TUNABLES2  bobtail   v0.55         v3.9
> CRUSH_TUNABLES3  firefly   v0.78         v3.15
> CRUSH_V4         hammer    v0.94         v4.1
> CRUSH_TUNABLES5  Jewel     v10.0.2       v4.5

当然，你也可以升级你的 Linux 内核来与之匹配。

访问模式

还有一个注意事项：CephFS 支持 3 种访问模式：ReadWriteOnce，ReadOnlyMany，ReadWriteMany，而 RBD 是块存储，仅支持两种：ReadWriteOnce，ReadOnlyMany。

其它问题

出现了错误仔细看一下 k8s 的报错信息，如果报错信息实在看不出什么，先检查一下各个参数有没有填对，比如 monitors 地址，密码之类的。

Xinzhao's Blog

Karmada Resource Interpreter Webhook 解析

Karmada 介绍

一个例子：创建一个 nginx 应用

Resource Interpreter Webhook

InterpretReplica

ReviseReplica

Workload 实现副本数调度

Retain

AggregateStatus

参考链接

Kubernetes 多集群项目介绍

为什么要使用集群联邦

Federation v1

Federation v2

Cluster Configuration

Type Configuration

Federated Resource CRD

Scheduling

Karmada

Cluster

Propagation Policy

Override Policy

Demo

参考链接

Kubernetes 组件单元测试指南

前言

使用 fake client

原生 client

generic client

构造轻量级集群

常用场景对比

Kubernetes CRD v1 介绍

前言

metadata

versions

schema

subresource

status subresource

scale subresource

参考链接

controller-runtime 介绍

概述

使用

Reconciler

介绍

使用示例

Builder 和 Manager

单元测试

总结

在使用 SharedInformerFactory 时一些很小但值得注意的问题

不要使用 goroutine 来启动 SharedInformerFactory

正确启动 SharedInformerFactory

使用 Ceph 做持久化存储的常见问题

前言

安装 Ceph 集群常见问题

不要用 root 用户

节点数量

关于 .ssh/config 文件

ImportError: No module named pkg_resources

RuntimeError: NoSectionError: No section: 'ceph'

使用 Ceph 的常见问题

Provisioner

Error creating rbd image: executable file not found in $PATH

feature set mismatch missing 400000000000000

访问模式

其它问题

关于 `.ssh/config` 文件