通过自定义资源扩展Kubernetes

Kubernetes是高度可配置、可扩展的，通常你不需要Fork其主项目代码或者打补丁。

对K8S的定制基本上可以分为两种方式：

1. 配置，例如修改命令行参数、本地配置、API资源
2. 扩展，在集群内外运行额外的程序或服务

本文主要讨论如何扩展K8S

扩展K8S的方式可以分为以下几类。

一种有效的编写客户程序的模式（Pattern）叫做控制器模式（Controller pattern），控制器负责执行例行性任务来保证集群尽可能接近其期望状态。典型情况下控制器读取.spec字段，运行一些逻辑，然后修改.status字段。K8S自身提供了大量的控制器，并由控制器管理器统一管理。

控制器是K8S的客户端。另一种扩展模式中，K8S作为客户端来访问外部服务。这种模式叫Webhook模式，被访问的外部服务叫做Webhook Backend。

和控制器一样，Webhook引入了故障点。

一段可执行的二进制程序，主要由kubelet、kubectl使用，例如 Flex卷插件、网络插件。

主要包括：

1. 可以扩展kubectl，但是仅仅影响用户本地环境
2. API访问扩展：API Server负责处理请求，它暴露了多个扩展点，允许对请求进行身份验证、基于内容阻塞请求、编辑请求内容、处理删除
3. 自定义资源：可以和API访问扩展联用，定义你自己的资源类型
4. 可以扩展调度器以调整Pod调度行为，可以完全替换为自己的实现
5. 控制器：很大一部分K8S行为由控制器实现，控制器是API Server的客户端，常和自定义资源联用
6. 定制网络插件、存储插件

“资源”对应着Kubernetes API中的一个端点（Endpoint），它存储了某种类型的API对象。自定义资源（Custom Resources）是对Kubernetes API的扩展，代表某种自定义的配置或独立运行的服务。

和内置资源一样，自定义资源本身仅仅是一段结构化数据，仅仅和相应自定义控制器联用后，才能作为声明式API。自定义资源描述了你期望的资源状态，由控制器来尽力达到此状态。

自定义控制器由用户部署到集群，这种控制器独立于集群本身的生命周期。尽管自定义控制器可以和任何类型的资源配合，但是对于自定义资源特别有意义。CoreOS提出的Operator Framework，就是自定义控制器联用自定义资源的例子。

有两种方法：

1. 使用CRD（CustomResourceDefinition）：
   1. 不需要编程
   2. 实现CRD控制器，可以使用任何编程语言
   3. 不需要额外的次级API Server，你不需要理解API聚合的概念
2. 使用API聚合（Aggregation）：
   1. 需要Go编程
   2. 可以对API行为进行更细粒度的控制——例如数据如何存储、如何在API版本之间转换
   3. 需要运行额外的API Server进程
   4. 需要自己处理多版本API的支持

CRD和API聚合都支持：

特性	说明
CRUD	通过HTTP或者kubectl，针对新端点进行增删改查操作
Watch	支持针对新端点的监控操作
Discovery	支持针对新端点的列出、查看、字段编辑等操作
json-patch	支持基于Content-Type: application/json-patch+json进行补丁操作
merge-patch	支持基于Content-Type: application/merge-patch+json进行补丁操作
HTTPS	支持HTTPS
身份验证	支持K8S身份验证
访问控制	支持RBAC等内置的K8S访问控制
Finalizers	阻塞删除操作，直到外部清理操作完毕
Admission Webhooks	在CRUD时，提供资源的默认值、验证资源定义的合法性
标签和注解	支持Label和Annotation

CRD是一种API资源，利用它你可以定义“自定义资源”，K8S负责CRD的存储。使用CRD而非API聚合可以免去编写次级API Server的烦恼，但是其灵活性不如API聚合。

CRD从1.7版本开始引入，到1.8版本进入Beta状态。最新的1.11版本CRD获得增强，支持scale、status子资源。

CRD/CR仅仅是一段声明信息，必须配合相应的控制器才有价值。

使用kubebuilder子项目controller-tools，配合一定的Tag，可以从CR类型源码生成CRD清单文件：

controller-gen会读取多种kubebuilder标记（Marker），详情请阅读kubebuilder一章。

CRD实际上是自定义资源的Schema，简单的例子：

执行下面的命令创建CRD：

监控CRD的condition Established，为true之后，可以通过API端点/apis/k8s.gmem.cc/v1/namespaces/*/crontabs/来管理自定义资源。

一旦CRD创建成功，你就可以创建对应类型的自定义资源（Custom Resource，CR）了。

自定义资源可以包含任意的自定义字段，例如：

当删除CRD后，所有基于它的自定义资源都自动被删除。

Finalizers用于实现资源的异步pre-delete钩子。自定义资源和内置资源一样，支持这种钩子。

通过metadata.finalizers字段来指定finalizers的数组，每个条目都是一个字符串。如果metadata.finalizers不为空，则对资源的强制删除无法执行。你应该使用准许控制，来确保必要的Finalizers添加到被删除的CR上。

对于具有finalizers的资源，向其发起第一次删除请求时，仅仅是设置 metadata.deletionTimestamp 字段。用来控制CRD的控制器，应该在Reconcile循环中发现deletionTimestamp非空（意味着对象应该被删除），并且：

1. 执行pre-delete钩子
2. 移除钩子对应的metadata.finalizers元素

当所有钩子执行完毕，finalizers被清空后，对象被真正的删除。所有pre-delete钩子执行可以消耗的总计时间，由metadata.deletionGracePeriodSeconds控制。

可以通过additionalPrinterColumns声明CRD的实例通过kubectl可以显示的额外字段：

你可以通过CRD的validation字段，来（基于 OpenAPI v3 Schema）规定自定义资源的字段验证规则。示例：

自定义资源可以支持/status和/scale子资源。此特性在1.11版本中处于Beta状态且默认启用。你需要在CRD中进行定义才能启用这些子资源。

scale子资源支持让其他K8S组件（例如HorizontalPodAutoscaler和PodDisruptionBudget控制器）与你的CR进行交互。kubectl scale也可以利用该子资源对CR进行扩容。

status子资源可以让你把资源的规格和状态分开。

启用状态子资源后，自定义资源的/status URL可用：

1. 数据对应资源的.status字段
2. PUT /status仅仅会修改.status字段，也仅仅对该字段进行验证
3. 对资源本身进行PUT/POST/PATCH操作，会忽视.status字段
4. 每次修改.spec字段，都导致.metadata.generation ++ 

启用扩容子资源后，自定义资源的/scale URL可用，RESTful载荷类型为autoscaling/v1.Scale

要启用扩容子资源，CRD需要指定：

1. SpecReplicasPath，指定自定义资源中对应Scale.Spec.Replicas的JSON路径。必须值
2. StatusReplicasPath，指定自定义资源中对应Scale.Status.Replicas的JSON路径。必须值
3. LabelSelectorPath，指定自定义资源中对应Scale.Status.Selector的JSON路径。可选值，和HPA联用则必须设置

示例：

用于指定资源所属的类别，例如all。示例：

通过kubectl get all可以访问到上述CRD的自定义资源。 

如果你的CRD中有个字段，可能容纳任何类型的对象，可以用结构包裹一个interface{}：

生成的CRD的OpenAPI校验，此字段校验规格自动为空： default: {}

helm-operator中的例子：

在准许控制（Admission Control）方面，自定义资源和内置资源没有什么区别。

可以参考Kubernetes学习笔记。本节额外给出针对自定义资源的Webhook示例。

本节的例子检查提交的CRD的GV，必须是apiextensions.k8s.io/v1beta1才准许通过：

本节的例子包含针对CR的validator、mutator：

开发控制器时常使用Go语言，基于K8S客户端库client-go。 你可以使用代码生成器减轻编写样板代码的负担，也可以考虑使用Operator Framework这样的提供高层API的框架。本章主要讨论基于client-go开发的控制器。

在控制器中，你通常需要提供一个无限的控制循环，用于管理系统状态。K8S的系统状态通过API Server暴露。

不管是使用Client-go，还是下文会讨论的Controller-runtime或者Operator Framework，控制器的架构都是一样的：

控制器主要使用以下client-go组件：

1. Informer/SharedInformer：监控目标K8S资源的变化，并交由ResourceEventHandler处理
2. ResourceEventHandler：通常是将事件发送到工作队列
3. Workqueue ：暂存资源变更事件，由控制循环取出事件并处理

此组件负责获取对象状态，通常你不会直接向API Server发请求，而是通过client-go提供的编程接口。client-go提供了缓存功能，避免反复从API Server获取数据。

如果仅仅需要关注对象的创建、修改、删除事件，可以使用ListerWatcher接口。该接口可以对特定的资源进行监控（watch）操作：

有了ListerWatcher你就可以创建Informer了：

实际编程时并不常使用Informer，下文会提到的SharedInformer使用的更多。

此接口包含两个函数：

上文调用的cache.NewListWatchFromClient，已经提供了ListWatcher的实现：

通常在此接口中提供事件处理逻辑：

规定每隔多久，控制器遍历缓存中所有对象，并调用OnUpdate。

如果控制器可能错过对象更新事件，或者先前的事件处理回调可能执行失败，则此配置参数很重要。

Informer会创建一个私有的缓存，其中包含它自己用到的所有资源。但是，在K8S中有很多控制器在运行，它们关注多种类型的对象。如果基于Informer实现这些控制器，就会有很多重复的缓存数据，增加资源占用。

SharedInformer能够创建一个共享的缓存，在多个控制器之间共享数据。此外，不管下游有多少个消费者，SharedInformer都仅仅对上游服务器建立一个Watch。因此SharedInformer同时降低了客户端的内存占用和服务器的负载。包含很多控制器的 kube-controller-manager使用SharedInformer。

SharedInformer直接提供了接受新增、更新、删除特定资源的钩子。

类似于Informer，cache模块也为SharedInformer提供了工厂函数：

由于SharedInformer是共享的，因此它不能跟踪每个控制器处理事件的进度。控制器必须提供自己的队列和重试（处理）机制。

当资源状态变化后，SharedInformer的ResourceEventHandler在Workqueue中添加一个Key。Key的格式是资源命名空间/资源名称，资源命名空间是可以省略的。

client-go/util/workqueue提供了多种工作队列的实现，包括：

1. 延迟队列，延后一段时间再将元素入队，由接口DelayingInterface提供
2. 限速队列，限定单位时间内能够入队的元素量，由接口RateLimitingInterface提供

下面的代码示意了如何创建限速队列：

一个Key在工作队列中的生命周期如下：

1. queue.Add(key)入队
2. queue.Get()获取第一个Key进行处理，如果：
   1. 处理成功，queue.Forget(key)清除掉Key
   2. 处理失败，在到达最大重试次数之前，控制器调用queue.AddRateLimited(key)重新入队
3. queue.Forget(key)仅仅让队列不再跟踪事件的历史。控制器会最终调用queue.Done()彻底删除事件

控制器仅仅（如果自己实现，也应该遵守此准则）在缓存完整同步后，才调用Worker，处理Workqueue，原因是：

1. 直到缓存同步完毕，列出的资源才是精确的
2. 可以让针对单个资源的多次更新合并为一个，避免反复处理中间状态，浪费资源

本节展示一个简单的控制器的例子。

直接进行类型断言即可，前提是你明白自己在监控什么对象：

你也可以用switch进行处理。

利用ObjectMeta.ResourceVersion，资源有变化后此字段即改变：

在1.7-版本中，操控CR需要基于client-go dynamic client，使用起来并不方便。

code-generator是K8S提供的一个代码生成器项目，可以用来：

1. 开发CRD的控制器时，生成版本化的、类型化的客户端代码（clientset），以及Lister、Informer代码
2. 开发API聚合时，在内部和版本化的类型、defaulters、protobuf编解码器、client、informer之间进行转换

K8S本身以及OpenShift也在使用此项目。

code-generator提供的，和CRD有关的生成器包括：

1. deepcopy-gen：为每个T类型生成 func (t* T) DeepCopy() *T方法。API类型都需要实现深拷贝
2. client-gen：为CustomResource API组生成强类型的clientset
3. informer-gen：为CustomResources生成Informer
4. lister-gen：为CustomResources生成Lister，Lister为GET/LIST请求提供只读缓存层

Informer和Lister是构建控制器（或者叫Operetor）的基本要素。使用这4个代码生成器可以创建全功能的、和K8S上游控制器工作机制相同的production-ready的控制器。

code-generator还包含一些其它的代码生成器。例如Conversion-gen负责产生内外部类型的转换函数、Defaulter-gen负责处理字段默认值。

crd-code-generation是使用代码生成器的一个示例项目，可以作为你的实际项目的起点。

code-generator基于k8s.io/gengo实现，两者共享一部分命令行标记。大部分的生成器支持--input-dirs参数来读取一系列输入包，处理其中的每个类型，然后生成代码：

1. 部分代码生成到输入包所在目录，例如deepcopy-gen生成器。可以使用参数 --output-file-base "zz_generated.deepcopy"来定义输出文件名
2. 其它代码生成到--output-package指定的目录（通常为pkg/client），例如client-gen、informer-gem、lister-gen等生成器

开发CRD时，你可以使用generator-group.sh脚本而不是逐个手工调用生成器。通常可以在项目中编写hack/update-codegen.sh：

执行上面的脚本后，所有API代码会生成在pkg/apis目录下，clientsets、informers、listers则生成在pkg/client目录下。 

你可以进一步提供hack/verify-codegen.sh脚本，用于判断生成的代码是否up-to-date：

除了通过命令行标记控制代码生成器之外，你还可以在go源码中使用tag来设定一些供生成器使用的属性。这些tag分为两类：

1. 在doc.go的package语句之上提供的全局tag
2. 在需要被处理的类型上提供的局部tag

tag的语法如下：

也就是说，tag是以注释的形式存在的。tag的位置很重要，很多tag必须直接位于type或package语句的上一行，另外一些则必须和go语句隔开至少一行空白。

必须在目标包的doc.go文件中声明，典型路径是 pkg/apis///doc.go。 内容示例：

要么直接声明在类型之前，要么位于类型之前的第二个注释块中。下面的 types.go中声明了CR对应的go类型：

内嵌了metav1.TypeMeta的资源通常都是顶级类型，实现runtime.Object，一般需要为它们生成client。

对于集群级别（非命名空间内）的资源，你需要提供：

你还可以控制客户端提供哪些HTTP方法：

项目的源码：https://git.gmem.cc/alex/demo-k8s-codegen.git。

使用dep进行依赖管理：

执行dep init 初始化项目，执行dep ensure下载依赖到vendor目录。

artifacts目录下存放CRD/CR的样例：

此CRD没有对CR的字段进行任何限定，如果需要进行验证，请使用validation。

hack目录存放的是执行代码生成的脚本，参考crd-code-generation项目的脚本，修改一下即可：

pkg/apis里面存放的是自定义资源的Go源码，以及deepcopy生成的zz_generated.deepcopy.go。

pkg/client里面存放的全部是自动生成的代码，包括clientset、informers、listers。

首先执行一次 dep ensure。相关依赖会下载到vendor目录下，由于k8s.io/client-go没有被import，因此不会下载。

调用update-codegen.sh，会生成若干个源码文件，如下图褐色字体所示：

再执行一次 dep ensure。 缺少的client-go依赖会自动下载。

首先创建CRD：

然后创建一个CR：

执行下面的命令可以看到已经创建的CR列表：

然后，编写一段测试代码，使用上述自动生成的clientset：

Operator Framework是一个开源工具箱，用于更高效的、自动化的、支持扩容的管理K8S Native应用程序。 该工具箱由CoreOS开发，目前尚处于alpha阶段，但是由controller-runtime提供的核心API已经比较稳定。

Operator是打包、部署、管理K8S应用程序（这里指既部署在K8S上，也通过K8S API或kubectl管理的应用程序）的方法。从概念上说，Operator将运维人员的运维知识编码到软件中，使之更容易打包、和客户分享。Operator比运维人员的人工判断要敏捷的多，它可以观测集群/应用的当前状态并在若干毫秒之内作出合理的运维决定。

Operator遵循如下成熟度模型：

可以实现基本的自动化运维，也可以定制针对特定应用程序的逻辑。高级的Operator可以实现无缝升级、自动处理故障……

Operator Framework由以下三部分组成：

1. Operator SDK：对开发者屏蔽K8S API的复杂性，简化Operator/Controller的开发
2. Operator Lifecycle Management：管理应用的安装、升级，管理K8S集群中运行的所有Operator（以及关联的Service）的生命周期
3. Operator Metering：提供Operator运行状况的监控指标

Operator SDK包含了构建、测试、打包Operator的工具。基于controller-runtime库，它提供了：

1. 高层次的API和抽象，让你能编写更加直白的运维逻辑
2. 用于快速开始一个新项目的代码生成器和脚手架
3. 覆盖一些通用Operator用例的模式，不需要重复造轮子

是运行在集群中的各种Operator的总控中心，它可以控制哪些Operator可以在哪些命名空间中运行，哪些用户可以和Operator进行交互。Lifecycle Manager也负责Operator及其关联资源的整体上的生命周期管理 —— 例如触发Operator及其关联资源的更新。

对于简单的无状态应用，无需编写代码，直接使用通用Operator（例如Helm Operator）即可。对于复杂的有状态应用，自定义Operator的价值更为突显，“云风格的”特性可以嵌入到Operator代码中，实现自动化的扩容、更新、备份，以提升用户体验。

在未来，Operator Framework将提供度量应用程序指标的能力。

你可以基于Go/Ansible开发Opearator 。基于Go的典型工作流程如下：

1. 使用SDK的CLI，创建一个新的Operator项目
2. 添加CRD，并定义一个新的资源API
3. 定义监控、调和（reconcile，通过适当的操作让资源接近期望状态）资源的控制器
4. 使用SDK、controller-runtime API来开发调和逻辑
5. 使用SDK CLI来构建、生成Operator的部署清单文件

开发Operator需要以下前置条件：dep 0.5+、git、go 1.10+、docker 17.03+、kubectl 1.11.0+，以及一个运行中的1.11.0+版本的K8S集群。

最新版本的Operator SDK使用Go modules机制，你需要设置环境变量：

如果你的网络无法访问Google，设置环境变量：

上述脚本执行后，会自动调用dep init创建项目，调用dep ensure下载依赖，并初始化Git仓库。 

最新版本的Operator SDK基于Go modules作为依赖管理工具而非dep。

上述命令完成后，会在pkg/apis目录下自动生成一系列文件，类似于code-generator。

执行下面的命令，为上节的API（资源）生成控制器：

上述命令完成后，会在pkg/controller目录生成控制器源码。

完成Operator逻辑开发后，执行下面的命令可以打包Docker镜像：

注意需要修改deploy/operator.yaml中的REPLACE_IMAGE为实际镜像名：

在开发期间，一般在本地运行Operator，以便快速测试和调试：

deploy目录下包括Operator对应的各种K8S资源，包括Deployment、Role、ServiceAccount，以及CRD和CR的样例。可以直接使用kubectl部署：

开发阶段完成后，建议使用Helm Chart打包封装。 

基于operator-sdk生成的Operator项目，其目录结构如下：

目录/文件	说明
cmd	manager/main.go为主函数，它： 初始化一个新的Manager 注册所有pkg/apis下定义的CR  启动所有pkg/controllers下定义的控制器
pkg/apis	包含CRD的API，开发人员需要编辑pkg/apis/GROUP/VERSION/KIND_types.go文件，为资源添加必要的字段
pkg/controller	包含控制器的实现，开发人员需要编辑pkg/controller/KIND/KIND_controller.go，实现KIND资源的Reconcile逻辑
build	包含Dockerfile，以及构建Operator所需的脚本
deploy	YAML形式的K8S资源定义文件，用于注册CRD、创建RABC、Deployment等资源
Gopkg.*	Go Dep的清单文件
vendor	为了满足项目import需要的外部依赖的副本

cmd/manager/main.go为Operator的入口点，它初始化一个Manager并运行。Manager会自动注册pkg/apis/下的自定义资源的Scheme，并运行pkg/controller/下的所有控制器。

Manager可以限制所有控制器可以监控的命名空间：

默认情况下监控Operator所在的命名空间，要监控所有命名空间，可以：

要添加新的CRD，执行：

之后你可以修改CR的Spec和Status类型，添加新字段：

修改*_types.go文件后，必须执行下面的命令，更新自动生成的代码： 

如果需要生成相应的Open API模型，还需要：

你需要为每个CRD添加控制器：

然后，你需要完成Operator调和逻辑的开发。例如，针对每个CR：

1. 如果Deployment不存在，则创建之
2. 确保Deployment的副本数满足MemcachedSpec.Size
3. 更新MemcachedStatus，也就是CR的Status字段

每个控制器都有一个Reconciler对象，该对象具有Reconcile()方法。Reconcile方法中实现了调和循环。调和循环接受Request参数，这是一个结构，它包含Namespace/Name形式的字串，可用于从缓存中查询到实际的对象：

根据你提供的返回值，Request可能被重新入队，导致调和循环再次触发：

你可以控制重新入队的延迟时间：

将控制器添加到Manager的时候，你需要发起资源监控，否则不会自动执行调和循环。

调用下面的方法可以监控针对CR的任何Add/Update/Delete事件，并发送Request对象给调和循环（Reconcile loop）：

调用下面的方法可以监控CR对应的Deployment（子对象），并发送Request —— 此Request将Deployment和它的Owner（也就是Memcached对象）关联起来：

在本节我们分析一下Operator SDK自动生成的代码框架的逻辑。

manager.New函数负责初始化全局的管理器：

创建控制器的逻辑在入口点中：

AddToManager是自动生成的：

每个控制器为AddToManagerFuncs添加一个成员，用于注册自己：

控制器是通过调用Controller接口的Start方法实现的。此方法会启动协程，协程的逻辑和4.3节手工编写的控制器基本一样，它调用Reconciler.Reconcile进行调和。

自动生成的框架代码中，提供了Reconciler的样例逻辑 —— 创建Pod：

Kubebuilder是一个开发CRD的框架，Operator Framework也在使用它。Kubebuilder辅助项目创建、CRD创建、调和循环编写、测试、镜像制作等开发流程，它提供了注释驱动（ //+）的代码生成器。

上述命令执行了，会自动生成一系列代码、配置文件，并且下载依赖包，最后进行构建。最终产生的目录结构如下：

通过查看入口点代码可以看出，和Operator Framework一样，kubebuilder使用controller-runtime库：

要watch指定的几个命名空间，可以使用：

上述命令将在api目录中生成自定义资源的Go类型：

自定义资源的GV信息定义在另一个文件中： 

创建API的时候，kubebuilder会交互式的提示，是否创建控制器。如果选择是，则会在controllers包生成控制器模板代码。

如果需要为CRD实现Admission Webhooks，仅仅实现Defaulter、 Validator接口即可。kubbuilder会自动完成其它工作：

1. 创建Webhook服务器
2. 确保Webhook服务器被控制器管理器管理
3. 创建Webhook需要的Handlers
4. 将Handler注册到URL路径

注意：大部分校验仅仅通过添加Marker即可实现，不需要Validating Webhook。

kubebuilder建议使用cert-manager来自动为Webhook Server提供数字证书。

cert-manager包含了一个名为CA injector的组件，能够自动为MutatingWebhookConfiguration、ValidatingWebhookConfiguration注入CA bundle。要使用该特性只需要添加特定的注解即可。参考下面的kustomize patch：

你可以在控制器中实现一段pre-delete钩子，直接编写在Reconile逻辑中即可。

Finalizers会导致delete变为update，设置一个删除时间戳。具有此时间戳的资源正在被删除，可以在控制器管理器的缓存中看到。

标记（Marker）是单行的、具有特殊格式的注释，它会影响kubebuilder的行为。

使用这些标记时，都需要 //+kubebuilder:前缀：

标记	说明
printcolumn	注释在类型上，为kubectl get增加输出列，属性列表： JSONPath 输出的属性路径 description 帮助信息 format 列格式 name 列名 priority 重要程度，整数 type 类型 示例： Go 1 // +kubebuilder:printcolumn:name="PrevLevel",type="string",JSONPath=".status.revLevel"
resource	注释在类型上，配置资源的命名、范围，属性列表： categories 所属目录 path 资源的复数形式 singular 资源的单数形式 scope 资源是否全局，取值Cluster、Namespaced shortName 资源的短名 示例： Go 1 2 // 生成非命名空间的CRD // +kubebuilder:resource:scope=Cluster
skipversion	注释在类型上，移除特定的资源版本
storageversion	注释在类型上，声明基于此版本存储CRD
subresource:scale	注释在类型上，定义scale子资源 Go 1 // +kubebuilder:subresource:scale
subresource:status	注释在类型上，定义状态子资源 Shell 1 // +kubebuilder:subresource:status
skip	注释在包上，不将此包作为API版本看待

参考：https://book.kubebuilder.io/reference/markers/crd-validation.html

标记	说明
kubebuilder:webhook	注释在类型上，决定生成的Webhook配置是什么样的，属性列表： failurePolicy，string：如果API Server无法访问Webhook Server会怎样 groups，string：此Webhook会接收针对什么API组的请求 mutating，bool：标记为Mutating webhook，设置为false则仅仅支持校验 name，string：配置的名称 path，string：API Server连接到Webhook Server的什么URL路径 resources，string：此Webhook会接收针对什么API资源的请求 verbs，string：此Webhook会接收针对什么方法的请求 versions，string：此Webhook会接收针对什么资源版本的请求

使用这些标记时，都需要 //+kubebuilder:前缀：

标记	说明
object:generate	注释在类型上，是否为类型启用deepcopy生成
object:root	注释在类型上，是否为类型启用接口实现的生成
object:generate	注释在包上，是否启用此包的deepcopy生成、接口（runtime.Object）实现生成

标记	说明
kubebuilder:rbac	注释在包上，用于生成一个RBAC ClusterRole清单文件，属性列表： groups，[]string 支持操作的组 namespace，string 支持操作的命名空间 resources，[]string 支持操作的资源 urls，[]string 支持操作的非资源URL verbs，[]string 支持的动词，小写

默认情况下，kubebuilder会在controllers/suite_test.go生成测试套件的骨架代码：

上述自动生成的代码并没有启动控制器，你需要添加相应逻辑：

理想情况下，对应每个在test_suite.go中调用的控制器，仅仅对应一个测试文件<kind>_conroller_test.go：

目标	说明
manifests	生成各种K8S资源的清单文件（YAML）
generate	生成代码

kubebuilder调用controller-gen命令来生成代码、YAML，controller-gen会读取各种标记。controller-gen支持多种生成器。

该项目包含若干Go库，用于快速构建控制器。Operator的SDK依赖于此项目。它使用controller-runtime的Client接口来实现针对K8S资源的CRUD操作。

用于启动（ Manager.Start）控制器，管理被多个控制器共享的依赖，例如Cache、Client、Scheme。

为读客户端提供本地缓存，支持监听更新缓存的事件。

实现针对K8S API Server的CRUD操作。读写客户端通常是分离（split）的。

Operator SDK通过manager.Manager来创建client.Client。SDK生成的代码中包含创建Manager的逻辑，Manager持有一个Cache和一个Client。 默认情况下Reconciler持有的Client是一个DelegatingClient：

DelegatingClient从Cache中读取（Get/List），写入（Create/Update/Delete）请求则直接发送给API Server。使用Cache可以大大减轻API Server的压力，随着缓存的更新，读操作会达成最终一致。

开发人员可能需要使用自己定制的客户端，直接从API Server读取，绕开缓存。你可以调用下面的方法新建客户端：

通常使用默认客户端就足够了。

获取单个对象：

示例代码：

查询一个对象列表：

示例代码：

创建一个新对象并提交到API Server：

示例：

示例：

示例：

 controller持有一个Reconciler，此外它从Manager得到各种共享对象，它自己创建一个工作队列。

controller.New负责创建控制器结构：

控制器可能会监控多种类型的对象（例如Pod + ReplicaSet + Deployment），但是控制器的Reconciler一般仅仅处理单一类型的对象。

当A类型的对象发生变化后，如果B类型的对象必须更新以响应，可以使用EnqueueRequestFromMapFunc来将一种类型的事件映射为另一种类型。例如Deployment的控制器可以使用EnqueueRequestForObject、EnqueueRequestForOwner实现：

1. 监控Deployment事件，并将Deployment的Namespace/Name入队
2. 监控ReplicaSet事件，并将创建它的Deployment（Owner）的Namespace/Name入队

类似ReplicaSet的控制器也可以监控ReplicaSet和Pod事件。

reconcile.Request入队时会自动去重。也就是说一个ReplicaSet创建的多个Pod事件可能仅仅触发ReplicaSet控制器的单次调用。

在Operator Framework中，本小节的逻辑样板代码自动生成在KIND/KIND_controller.go文件中。

Reconciler是Controller的组件，是Controller的核心逻辑所在。它负责调和 —— 逼近期望状态。例如，当针对ReplicaSet对象调用Reconciler时，发现ReplicaSet要求5实例，但是当前系统中只有3个Pod，这时Reconciler应该创建额外的两个Pod，并且将这些Pod的OwnerReference指向前面的ReplicaSet。

Reconciler通常仅处理一种类型的对象，OwnerReference用于从子对象（例如Pod）触发父对象的调和（例如ReplicaSet）操作。

Reconciler实现reconcile.Reconciler接口，该接口暴露了一个Reconcile方法。该方法在集群内外事件发生时被调用，入参是reconcile.Request。Request不包含事件的细节，它仅仅提供查询资源所需的键，出参是reconcile.Result。Reconciler持有Client以便访问API Server：

Admission Webhooks是扩展Kubernetes API的一种方式。API Server作为Webhook的客户端，当特定事件发生时，发送AdmissionRequest给Webhook。

Webhook分为两种：

1. Mutating webhook：在API Server正式接受之前，修改核心API对象或者CRD实例
2. Validating webhook：验证对象是否满足特定要求

它们都通过Handler来操作AdmissionReview中内嵌的对象。

resource.Source是提供给Controller.Watch的参数，提供事件的流。这些事件通常是通过Watch API Server得到的。

大多数情况下，你不需要自己实现Source。

handler.EventHandler是提供给Controller.Watch的参数，负责响应事件：

1. EventHandler通常会为一个或多个对象产生reconcile.Request并入队
2. EventHandler可能会将一种对象的事件，映射为同一种对象的Request
3. EventHandler可能会将一种对象的事件，映射为另一种对象的Request —— 例如，将Pod对象的事件映射为拥有Pod的ReplicaSet的Request
4. EventHandler可能会将一种对象的一个事件，迎合为相同/不同对象的多个Request

大多数情况下，你不需要自己实现EventHandler。

handler.EventHandler是提供给Controller.Watch的可选参数，用于实现事件的过滤，Predicate入参是一个事件，返回bool。

你应当尽量使用既有的Predicate实现。

Redis Operator是开源的Redis Cluster Operator， 它的目的是在K8S环境下使用Redis集群的自动化运维。本章通过解析它的源码来学习Operator开发的实战经验。本章使用的Redis Operator是gmemcc分支出的版本。

Redis Operator没有使用Operator SDK，但使用了code-generator进行代码生成。

描述Redis集群的配置：

描述Redis集群的状态，Operator负责分析真实状态并更新该结构。

对RedisCluster运维工作流的某个Condition进行建模：

Condition，字面意思是条件、状况。在K8S环境下，表示了资源的某种状态值，取值总是True、False、Unknown之一。 这些状态，有时候对应了资源生命周期的某个阶段，或者说是自动化运维流程的某个环节。

例如一个Pod的Condition类型包括：PodScheduled、Initialized、ContainersReady、Ready。而RedisCluster的Condition类型则包括：

描述Redis集群的状态：

全局状态值：

节点信息：

Redis Operator的入口点定义在redis-operator/cmd/operator/main.go中。程序启动时，首先利用pflag解析命令行参数，生成一个Config结构，然后创建Operator实例：

Operator构建完成后，调用其Run函数启动若干例程：

NewRedisOperator函数的逻辑主要包括：

1. 注册自定义资源RedisCluster的CRD到API Server
2. 创建CR的客户端
3. 创建K8S资源的Informer工厂，以及CR的Informer工厂
4. 创建Controller对象
5. 创建垃圾回收器对象
6. 创建RedisOperator实例
7. 初始化Operator的健康检查服务

NewRedisOperator会先初始化K8S客户端配置，然后尝试注册CRD：

下面是注册CRD的细节： 

NewRedisOperator会根据kubeconfig来创建操控RedisCluster的客户端：

NewClient的代码如下：

用于提供API Server的客户端缓存、Lister接口。

Redis Operator使用heptiolabs/healthcheck库，实现Operator本身的健康检查：

Redis Operator的信号处理部分利用了Context，使用Context可以方便的控制多个相互协作的Goroutine：

Redis Operator的所有例程都会等待Context.Done() 关闭，并结束处理逻辑。

Operator的Run方法启动若干例程：

核心逻辑在控制器中。 

各种Lister字段都是通过Informer工厂得到的：

各种Control属于Redis Operator的内部细节，用于对相应的API资源进行CRUD。

控制器的总体逻辑如下：

封装在控制器的runWorker方法中：

当创建一个新的RedisCluster对象，或者既有RedisCluster被修改后，此方法会被调和循环所调用。

首先从缓存中查询到RedisCulster对象，此对象应该只读访问：

如果RedisCluster对象缺少必要的字段，则添加这些字段，并结束处理：

如果RedisCluster已经被请求删除，则不对事件进行处理：

如果Status.StartTime字段为空，则初始化之，并结束处理：

如果上面三个异常情况都不存在，则调用syncCluster方法，该方法包含了Redis Operator的核心业务逻辑。

此方法返回一个redis.AdminInterface接口，可以管理一组Redis节点，以及这些节点所属的Redis集群：

AdminInterface内部使用radix.v2 —— Redis的Go客户端 —— 来操控Redis集群。

执行Redis集群状态完整性检查，如果dryRun为true，则不对集群进行变更。

对Redis Pod、Redis集群进行各种管理操作，以逼近期望状态：

此方法可能会添加、删除Pod，或者对Redis进程进行配置：

GitHub下载源码：

构建：

使用Helm部署Operator：

用Goland打开下载的项目，参考下图创建Debug Configuration：

通过学习Redis Operator的源码，我们了解到：

1. 可以编程式的创建CRD
2. 使用Condition来建模资源的生命周期阶段，例如“扩容中”
3. 修改任何共享数据结构前，先深拷贝它
4. 正确设置各种子资源的OwnerReferences，保证CR被删除后，它们能被级联的处理
5. 如果资源的真实状态和CR.Status中记录的状态不一致，应当立即同步，然后将事件重新入队，结束本次处理
6. 等待所有实例（Pod）准备好以后，再进一步调和
7. 每次调和，做一点点事情，让逻辑简单可控。Redis Operator在单次调和中可能：
   1. 更新CR的Status字段
   2. 创建一个Pod
   3. 修改Redis集群配置
8. Operator本身应该具有健康检查机制

报错信息：Dependency manager "modules" has been selected but go modules are not active. Activate modules then run "operator-sdk new helm-services"

解决方案：设置环境变量 GO111MODULE=on

报错： Failed to get API Group-Resources {"error": "Get \"https://10.0.3.1:6443/api?timeout=32s\": Access violation"}

原因是使用了代理。