k8s-vgpu-scheduler是由第四范式开源的基于Kubernetes平台的GPU虚拟化项目，本人在之前的文章中曾经简单介绍过。在今年，k8s-vgpu-scheduler正式改名为[HAMi](https://github.com/Project-HAMi/HAMi), 并加入了CNCF. 本文将基于HAMi对vgpu scheduler部分进行代码分析。



# 总览
k8s-vgpu-scheduler会起一个自定义scheduler，并在scheduler的配置中配置extender. 这个自定义的scheduler叫做4pd-scheduler, 通过KubeSchedulerConfiguration, 该schduler与gpu相关的资源绑定，当pod申请gpu相关资源时，会由4pd-scheduler进行调度。

# scheduler
[官方文档](https://kubernetes.io/zh-cn/docs/tasks/extend-kubernetes/configure-multiple-schedulers/) 对如何运行自己的scheduler进行了介绍。在vgpu-scheduler项目中，是直接运行了一个官方的kube-scheduler实例：
```yaml
      containers:
        - name: kube-scheduler
          image: {{ .Values.scheduler.kubeScheduler.image }}:{{ .Values.scheduler.kubeScheduler.imageTag }}
          imagePullPolicy: {{ .Values.scheduler.kubeScheduler.imagePullPolicy | quote }}
          command:
            - kube-scheduler
            {{- if ge (.Values.scheduler.kubeScheduler.imageTag | substr 3 5| atoi) 22}}
            {{- range .Values.scheduler.kubeScheduler.extraNewArgs }}
            - {{ . }}
            {{- end }}
            {{- else }}
            - --scheduler-name={{ .Values.schedulerName }}
            {{- range .Values.scheduler.kubeScheduler.extraArgs }}
            - {{ . }}
            {{- end }}
            {{- end }}
```

## scheduler 配置
通过配置文件，该scheduler定制成了vgpu-scheduler. 需要注意的是，在k8s 1.22之后，scheduler的配置方式发生了变化。
### 1.22及更早
需要加上启动参数`--scheduler-name=$scheduler_name`和`--leader-elect=false`
通过`--policy-config-file`指定配置文件，格式为json, 该配置文件内容称为scheduler policy.
我们查看vgpu-scheduler的scheduler policy:
```json
{
    "kind": "Policy",
    "apiVersion": "v1",
    "extenders": [
        {
            "urlPrefix": "https://127.0.0.1:443",
            "filterVerb": "filter",
            "bindVerb": "bind",
            "enableHttps": true,
            "weight": 1,
            "nodeCacheCapable": true,
            "httpTimeout": 30000000000,
            "tlsConfig": {
                "insecure": true
            },
            "managedResources": [
                {
                    "name": "{{ .Values.resourceName }}",
                    "ignoredByScheduler": true
                },
                {
                    "name": "{{ .Values.resourceMem }}",
                    "ignoredByScheduler": true
                },
                {
                    "name": "{{ .Values.resourceCores }}",
                    "ignoredByScheduler": true
                },
                {
                    "name": "{{ .Values.resourceMemPercentage }}",
                    "ignoredByScheduler": true
                },
                {
                    "name": "{{ .Values.resourcePriority }}",
                    "ignoredByScheduler": true
                },
                {
                    "name": "{{ .Values.mluResourceName }}",
                    "ignoredByScheduler": true
                },
                {
                    "name": "{{ .Values.mluResourceMem }}",
                    "ignoredByScheduler": true   
                }
            ],
            "ignoreable": false
        }
    ]
}
```
可以看到主要是配置了extender和managedResources. extender主要用于做调度的决策，managedResources决定了哪些pod会由该scheduler调度。后面会详解这两部分。

### 1.22之后
通过`--config=/config/config.yaml`指定配置文件，格式为yaml, 文件内容为 KubeSchedulerConfiguration
关于1.22之后的 scheduler如何配置，参考[官方文档](https://kubernetes.io/docs/reference/scheduling/config/#multiple-profiles)。
KubeSchedulerConfiguration  的字段，可以参考[API文档](https://kubernetes.io/zh-cn/docs/reference/config-api/kube-scheduler-config.v1/#kubescheduler-config-k8s-io-v1-KubeSchedulerConfiguration)。
具体到vgpu-scheduler, KubeSchedulerConfiguration 内容如下：
```yaml
apiVersion: kubescheduler.config.k8s.io/v1beta2
kind: KubeSchedulerConfiguration
leaderElection:
  leaderElect: false
profiles:
- schedulerName: {{ .Values.schedulerName }}
extenders:
- urlPrefix: "https://127.0.0.1:443"
  filterVerb: filter
  bindVerb: bind
  nodeCacheCapable: true
  weight: 1
  httpTimeout: 30s
  enableHTTPS: true
  tlsConfig:
    insecure: true
  managedResources:
  - name: {{ .Values.resourceName }}
    ignoredByScheduler: true
  - name: {{ .Values.resourceMem }}
    ignoredByScheduler: true
  - name: {{ .Values.resourceCores }}
    ignoredByScheduler: true
  - name: {{ .Values.resourceMemPercentage }}
    ignoredByScheduler: true
  - name: {{ .Values.resourcePriority }}
    ignoredByScheduler: true
  - name: {{ .Values.mluResourceName }}
    ignoredByScheduler: true
  - name: {{ .Values.mluResourceMem }}
    ignoredByScheduler: true
```

## managedResources

那么，当我们创建一个GPU的pod, k8s是如何判断要使用vgpu-scheduler呢？从[API文档](https://kubernetes.io/zh-cn/docs/reference/config-api/kube-scheduler-config.v1/#kubescheduler-config-k8s-io-v1-KubeSchedulerConfiguration) 中 KubeSchedulerConfiguration.externders.managedResources 的描述可以看到：
```
managedResources
[]ExtenderManagedResource	
managedResources 是一个由此扩展模块所管理的扩展资源的列表。
如果某 Pod 请求了此列表中的至少一个扩展资源，则 Pod 会在 filter、 prioritize 和 bind （如果扩展模块可以执行绑定操作）阶段被发送到该扩展模块。
如果某资源上设置了 ignoredByScheduler 为 true，则 kube-scheduler 会在断言阶段略过对该资源的检查。
```

# scheduler extender
k8s 的调度包含三个阶段：predicate(filter), prioritize and bind. 在 kube-scheduler 的配置中，甚至提供了[12个调度阶段的插件配置](https://kubernetes.io/docs/reference/scheduling/config/#extension-points) 。
scheduler extender 本质上是一个 webhook, scheduler 在调度的三个阶段（还有一个preempt, 抢占式调度，本文暂不介绍）会调用 extender 的对应接口，从而得到最终的调度结果。[参考这里](https://github.com/generals-space/kube-scheduler-extender?tab=readme-ov-file#%E5%89%8D%E8%A8%80) 文中给出了一个流程图：
```
       kube-scheduler                                kube-scheduler-extender(HttpAPI)
+------------|-------------+                          +--------------------------+
|            |             |                          |                          |
|    +-------↓--------+    |      Pod + []Node        |    +----------------+    |
|    |                ├───────────────────────────────────>|                |    |
|    |   predicates   |    |                          |    |   predicates   |    |
|    |                |<───────────────────────────────────┤                |    |
|    +-------┬--------+    |     []Node(filtered)     |    +----------------+    |
|            |             |                          |                          |
|            |             |                          |                          |
|    +-------↓--------+    |       Pod + []Node       |    +----------------+    |
|    |                ├───────────────────────────────────>|                |    |
|    |   prioritize   |    |                          |    |   prioritize   |    |
|    |                |<───────────────────────────────────┤                |    |
|    +-------┬--------+    |      []Node(scored)      |    +----------------+    |
|            |             |                          |                          |
|            |             |                          |                          |
|    +-------↓--------+    |        Pod + Node        |    +----------------+    |
|    |                ├───────────────────────────────────>|                |    |
|    |      bind      |    |                          |    |      bind      |    |
|    |                |<───────────────────────────────────┤                |    |
|    +-------┬--------+    |        Error/nil         |    +----------------+    |
|            |             |                          |                          |
|            |             |                          |                          |
+------------|-------------+                          +--------------------------+
             ↓                                                                    
```
scheduler extender 的官方设计文档在 [这里](https://github.com/kubernetes/design-proposals-archive/blob/main/scheduling/scheduler_extender.md)。注意该文档提供的配置文件格式是k8s 1.23版本之前的格式。

查看vgpu-scheduler extender的代码，发现是一个http服务，在`cmd/scheduler/main.go`中注册了三个handler:
```go
router := httprouter.New()
router.POST("/filter", routes.PredicateRoute(sher))
router.POST("/bind", routes.Bind(sher))
router.POST("/webhook", routes.WebHookRoute())
```
结合上面的 KubeSchedulerConfiguration, 可以知道实现了filter(即predicate)和bind两个调度过程的接口，至于preempt和prioritize则没有实现。而webhook接口主要是使用admission webhook对pod yaml进行修改。

## filter(predicate)
filter阶段主要用于过滤掉pod不能运行的节点，然而在k8s-vgpu-scheduler中把prioritize, 即优选节点的工作也做了。k8s-vgpu-scheduler的filter逻辑在`pkg/scheduler/scheduler.go`中实现，主要包括几步：
1. 确认pod有请求vGPU资源
2. 计算接收的参数中每个节点的可用vGPU资源
3. 对所有节点进行计算打分并排序
4. 将得分最高的节点作为调度目标节点，通过annotation注入到pod yaml中
5. 返回调度目标节点ID作为调度结果

### 计算接收的参数中每个节点的可用vGPU资源
该步骤由`pkg/scheduler/scheduler.go`中的`getNodesUsage`函数完成：
创建三个映射：overallnodeMap用于存储所有节点的使用情况，cachenodeMap用于存储入参节点列表中节点的使用情况，failedNodes用于存储失败节点的信息。
```go
	overallnodeMap := make(map[string]*NodeUsage)
	cachenodeMap := make(map[string]*NodeUsage)
	failedNodes := make(map[string]string)
```
调用Scheduler的ListNodes方法获取所有节点的信息。如果出现错误，返回overallnodeMap、failedNodes和错误。
```go
	allNodes, err := s.ListNodes()
	if err != nil {
		return &overallnodeMap, failedNodes, err
	}
```
遍历所有节点，为每个节点创建一个NodeUsage对象，并根据节点的设备信息初始化DeviceUsageList。
```go
	for _, node := range allNodes {
		nodeInfo := &NodeUsage{}
```
如果提供了task（Pod），则从其注解中获取GPU调度策略，否则使用默认策略。
```go
		userGPUPolicy := config.GPUSchedulerPolicy
		if task != nil && task.Annotations != nil {
			if value, ok := task.Annotations[policy.GPUSchedulerPolicyAnnotationKey]; ok {
				userGPUPolicy = value
			}
		}
```
遍历节点的设备信息，为每个设备创建一个DeviceUsage对象，并将其添加到DeviceUsageList中。
```go
		nodeInfo.Devices = policy.DeviceUsageList{
			Policy:      userGPUPolicy,
			DeviceLists: make([]*policy.DeviceListsScore, 0),
		}
		for _, d := range node.Devices {
			nodeInfo.Devices.DeviceLists = append(nodeInfo.Devices.DeviceLists, &policy.DeviceListsScore{
				Score: 0,
				Device: &util.DeviceUsage{
					ID:        d.ID,
					Index:     d.Index,
					Used:      0,
					Count:     d.Count,
					Usedmem:   0,
					Totalmem:  d.Devmem,
					Totalcore: d.Devcore,
					Usedcores: 0,
					Type:      d.Type,
					Numa:      d.Numa,
					Health:    d.Health,
				},
			})
		}
		overallnodeMap[node.ID] = nodeInfo
	}
```
遍历Scheduler中已分配的Pods，根据Pod的节点ID查找对应的节点使用情况。
遍历Pod的设备信息，根据设备的UUID更新对应节点设备的使用情况。
使用klog记录设备的使用情况。
更新Scheduler的overviewstatus为overallnodeMap。
```go
	for _, p := range s.pods {
		node, ok := overallnodeMap[p.NodeID]
		if !ok {
			continue
		}
		for _, podsingleds := range p.Devices {
			for _, ctrdevs := range podsingleds {
				for _, udevice := range ctrdevs {
					for _, d := range node.Devices.DeviceLists {
						if d.Device.ID == udevice.UUID {
							d.Device.Used++
							d.Device.Usedmem += udevice.Usedmem
							d.Device.Usedcores += udevice.Usedcores
						}
					}
				}
			}
		}
		klog.V(5).Infof("usage: pod %v assigned %v %v", p.Name, p.NodeID, p.Devices)
	}
	s.overviewstatus = overallnodeMap
```
遍历提供的节点列表，获取节点信息。如果获取失败，将节点ID和错误信息添加到failedNodes中。否则，将节点的使用情况添加到cachenodeMap中。
更新Scheduler的cachedstatus为cachenodeMap。
返回cachenodeMap、failedNodes和nil。
```go
	for _, nodeID := range *nodes {
		node, err := s.GetNode(nodeID)
		if err != nil {
			klog.Warningf("get node %v device error, %v", nodeID, err)
			failedNodes[nodeID] = "node unregisterd"
			continue
		}
		cachenodeMap[node.ID] = overallnodeMap[node.ID]
	}
	s.cachedstatus = cachenodeMap
	return &cachenodeMap, failedNodes, nil
```

## bind
bind函数首先将node上锁
```go
	tmppatch := make(map[string]string)
	for _, val := range device.GetDevices() {
		err = val.LockNode(node, current)
		if err != nil {
			goto RelaseNodeLocks
		}
	}
```
然后通过annotation给pod加上allocating状态；至于何时将pod状态更新为分配成功或者失败，则是由device plugin完成的
```go
	tmppatch[util.DeviceBindPhase] = "allocating"
	tmppatch[util.BindTimeAnnotations] = strconv.FormatInt(time.Now().Unix(), 10)

	err = util.PatchPodAnnotations(current, tmppatch)
	if err != nil {
		klog.ErrorS(err, "patch pod annotation failed")
	}
```
最后调用Bind函数将pod与node进行绑定
```go
if err = s.kubeClient.CoreV1().Pods(args.PodNamespace).Bind(context.Background(), binding, metav1.CreateOptions{}); err != nil {
		klog.ErrorS(err, "Failed to bind pod", "pod", args.PodName, "namespace", args.PodNamespace, "podUID", args.PodUID, "node", args.Node)
	}
	if err == nil {
		res = &extenderv1.ExtenderBindingResult{
			Error: "",
		}
		klog.Infoln("After Binding Process")
		return res, nil
	}
```
当然，最后还需要将node解锁

## mutate(adminssion webhook)
webhook接口主要是在pod提交创建时对pod的yaml进行修改，由于本文主要介绍scheduler的部分，adminssion webhook只做简单介绍，详细原理计划在另外一篇文章介绍。
webhook的逻辑比较简单，主要是：
1. 针对设置了gpucore, gpumem 和 gpumempercentage 但没有设置gpu数量的pod，加上默认gpu数量的request和limit
2. 设置pod的scheduler name, 指定后续调度由vgpu scheduler完成

k8s-vgpu-scheduler调度分析

本文分享一点雾凇拼音的使用心得


雾凇拼音是一套rime的词库方案  
介绍：https://dvel.me/posts/rime-ice/  
github: https://github.com/iDvel/rime-ice

使用方法  
先安装rime, 比如windows安装小狼毫  
进入小狼毫用户文件夹，把原来的文件备份然后全部删掉  
在用户文件夹，使用git下载雾凇拼音的配置
```bash
git clone https://github.com/iDvel/rime-ice.git
```
后期如果要更新，直接通过git操作即可

运行`【小狼毫】输入法设定`，选择开启的方案和主题，配置会保存在`weasel.custom.yaml`  
其它设置可以放在`default.custom.yaml`, 下面是一个例子：
```yaml
patch:
  menu/page_size: 9
  key_binder/bindings/+: #配置逗号和句号翻页
    - { when: paging, accept: comma, send: Page_Up }
    - { when: has_menu, accept: period, send: Page_Down }
  switcher:
    caption: 「方案选单」
    hotkeys:
      - F4
      - Control+Shift+grave
  ascii_composer/switch_key/Shift_L: noop
  recognizer/patterns/minus: "^[A-Za-z]+-.*" #减号不上屏，如果用减号翻页得去掉
  recognizer/patterns/equal: "^[A-Za-z]+=.*" #等于号不上屏，如果用等于号翻页得去掉
```
注意：`weasel.custom.yaml`和`default.custom.yaml`不会保存到git历史中

雾凇拼音

本文介绍使用kubebuilder搭建一个kubernetes CRD crontroller框架，并使用code generator生产对应的clientset/informers/listers.




# kubebuilder
https://book.kubebuilder.io/introduction.html

## 安装
```bash
curl -L -o kubebuilder "https://go.kubebuilder.io/dl/latest/$(go env GOOS)/$(go env GOARCH)"
```

## 初始化
```bash
mkdir -p ${GOPATH}/guestbook/src/example
cd ${GOPATH}/guestbook/src/example
kubebuilder init --domain my.domain
```
如果项目路径没有按照gopath的格式，则需要加上`--repo`参数：
```bash
kubebuilder init --domain my.domain --repo my.domain/guestbook
```

## 创建api
```bash
kubebuilder create api --group webapp --version v1 --kind Guestbook
```
`INFO Create Resource [y/n]` 选y会创建`api/v1/guestbook_types.go`

`INFO Create Controller [y/n]`选y会创建`internal/controllers/guestbook_controller.go`

## 修改api定义和controller逻辑
使用`make manifests`更新CRD

如果要创建已有资源的controller，需要指定group为core，参考https://github.com/kubernetes-sigs/kubebuilder/issues/1270  
官方参考代码：https://github.com/kubernetes-sigs/controller-runtime/tree/master/examples/builtins
```bash
kubebuilder create api --group core --version v1 --kind Node
# Create Resource [y/n] 选n
# Create Controller [y/n] 选y
```



# kubebuilder与code generator的区别
Kubebuilder不会生成informers、listers、clientsets，而code-generator会。  
Kubebuilder会生成Controller、Admission Webhooks，而code-generator不会。  
Kubebuilder会生成manifests yaml，而code-generator不会。
Kubebuilder还带有一些其他便利性设施。

ref: https://cloud.tencent.com/developer/article/1656317

# code generator
## 安装
注意K8S_VERSION必须和go.mod里面的一致
```bash
K8S_VERSION=v0.29.0
go get k8s.io/code-generator@$K8S_VERSION
```

## 添加脚本
`hack/update-codegen.sh`  
参考：https://github.com/kubernetes/code-generator/raw/v0.29.0/examples/hack/update-codegen.sh  
最终修改的版本：
<details>
  <summary>点击展开</summary>

```bash
#!/usr/bin/env bash

# Copyright 2017 The Kubernetes Authors.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

set -x
set -o errexit
set -o nounset
set -o pipefail

SCRIPT_DIR="$(dirname "${BASH_SOURCE[0]}")"
SCRIPT_ROOT="${SCRIPT_DIR}/.."
CODEGEN_PKG="${CODEGEN_PKG:-"${SCRIPT_ROOT}/.."}"

source "${CODEGEN_PKG}/kube_codegen.sh"

# generate the code with:
# - --output-base because this script should also be able to run inside the vendor dir of
#   k8s.io/kubernetes. The output-base is needed for the generators to output into the vendor dir
#   instead of the $GOPATH directly. For normal projects this can be dropped.

kube::codegen::gen_helpers \
    --input-pkg-root . \
    --output-base ${SCRIPT_ROOT} \
    --boilerplate "${SCRIPT_ROOT}/hack/boilerplate.go.txt"

if [[ -n "${API_KNOWN_VIOLATIONS_DIR:-}" ]]; then
    report_filename="${API_KNOWN_VIOLATIONS_DIR}/codegen_violation_exceptions.list"
    if [[ "${UPDATE_API_KNOWN_VIOLATIONS:-}" == "true" ]]; then
        update_report="--update-report"
    fi
fi

kube::codegen::gen_openapi \
    --input-pkg-root . \
    --output-pkg-root . \
    --output-base ${SCRIPT_ROOT} \
    --report-filename "${report_filename:-"/dev/null"}" \
    ${update_report:+"${update_report}"} \
    --boilerplate "${SCRIPT_ROOT}/hack/boilerplate.go.txt"

kube::codegen::gen_client \
    --with-watch \
    --input-pkg-root . \
    --output-pkg-root . \
    --output-base ${SCRIPT_ROOT} \
    --boilerplate "${SCRIPT_ROOT}/hack/boilerplate.go.txt"
```
</details>

`hack/verify-codegen.sh` https://github.com/kubernetes/code-generator/raw/v0.29.0/examples/hack/verify-codegen.sh

`hack/kube_codegen.sh` https://github.com/kubernetes/code-generator/raw/v0.29.0/kube_codegen.sh  
修改一个地方：
```bash
    done < <(
        ( kube::codegen::internal::git_grep -l \
            -e '+genclient' \
            ":(glob)${in_root}"/'**/*types.go' \ //这里types.go前面加上星号
            || true \
        ) | LC_ALL=C sort -u
    )
```

## 修改代码
修改`api/v1/guestbook_types.go`，在`type Guestbook struct`上面添加：
```go
//+genclient
```
如果要全局生效，可以创建一个doc.go文件，把注释写在里面：
```go
// +groupName=my.domain/guestbook
// +genclient

package v1
```
各种注释的作用(来自chatgpt)：
- genclient  
注释 `+genclient` 用于指示 Kubernetes 的代码生成工具 client-gen 为特定的 API 类型生成客户端代码。这个客户端代码包含了与 Kubernetes API 交互所需的方法，例如创建、获取、更新和删除资源对象。
当你在 API 类型定义文件中添加了 +genclient 注释时，client-gen 工具会为该类型生成一个客户端接口，这个接口包含了一系列标准的客户端操作方法。这些方法对应于 Kubernetes API 的操作，使得开发者可以在他们的应用程序中方便地管理 Kubernetes 资源。  
此外，`+genclient` 注释还可以与其他选项一起使用，以定制生成的客户端代码的行为。例如：  
`+genclient:noStatus`：即使 .Status 字段存在，也不生成 updateStatus 方法。  
`+genclient:nonNamespaced`：为集群范围的资源（不属于任何命名空间的资源）生成客户端代码。  
`+genclient:onlyVerbs=create,get`：只为指定的动作生成客户端方法。  
`+genclient:skipVerbs=watch`：生成除 watch 之外的所有客户端方法。

- deecopy-gen  
注释 `+k8s:deepcopy-gen` 用于指示 Kubernetes 的代码生成工具为特定的 Go 包中的类型生成 DeepCopy 方法。这是 Kubernetes 自定义资源定义（CRD）开发过程中的一个重要步骤，因为它确保了类型的每个实例都可以被安全地复制，这对于 Kubernetes 的许多操作来说是必需的。  
由于kubebuilder已经为crd生成了deepcopy函数，所以这个注释可以不用

- defaulter-gen  
注释 `+k8s:defaulter-gen` 是 Kubernetes 代码生成工具中使用的一个标记，它用于为特定的 Go 包中的类型生成默认值设置函数。这些函数通常在 API 对象被创建或更新时调用，以确保所有未设置的字段都有合适的默认值。当你在包的 doc.go 文件或类型定义文件中添加了 `+k8s:defaulter-gen=TypeMeta` 注释时，code-generator 工具会为该包中的所有公开类型生成默认值设置函数。如果你想为特定的类型生成默认值设置函数，可以在类型定义上使用 `+k8s:defaulter-gen=true` 注释。

- conversion-gen  
注释 `+k8s:conversion-gen` 用于指导 Kubernetes 的代码生成工具 conversion-gen 自动生成在内部和外部类型之间转换的函数。这些转换函数对于 Kubernetes API 中的多版本支持非常重要，因为它们允许不同版本的 API 对象之间进行转换。  
具体来说，conversion-gen 工具会生成函数，这些函数能够高效地在具有相同名称的类型之间进行转换，无论这些类型是定义在内部包还是外部包中。生成的函数包括 `autoConvert_<pkg1>_<type>_To_<pkg2>_<type>`，这些函数会递归地处理数据类型的结构。对于结构体，它会根据名称匹配源字段和目标字段；如果源字段没有对应的目标字段，或者字段类型存在根本的不匹配，那么生成的 `autoConvert_...` 函数将只包含一个关于该字段的警告注释。

- openapi-gen  
注释 `+k8s:openapi-gen` 用于指导 Kubernetes 代码生成工具 openapi-gen 为 Go 包中的类型生成 OpenAPI 规范。这个规范定义了 RESTful API 的接口，使得人类和计算机都能理解服务的功能，而无需接触源代码或监控网络通信。  
当你在包的 doc.go 文件或类型定义文件中添加了 `+k8s:openapi-gen` 注释时，openapi-gen 工具会扫描该包下的所有类型，并为它们生成 OpenAPI 定义。这样，Kubernetes 就可以使用文档生成工具来展示其 API，使用代码生成工具来自动生成服务器端和客户端的代码，以及使用自动测试工具进行测试。

## 生成代码
```bash
export CODEGEN_PKG=./hack/
./hack/update-codegen.sh
```
如果报错：
`/data/go/pkg/mod/k8s.io/code-generator@v0.29.0/cmd/openapi-gen/main.go:37:43: undefined: generatorargs.NewDefaults`

需要更新kube-openapi  
```bash
go get k8s.io/kube-openapi@v0.0.0-20231010175941-2dd684a91f00
```
版本是从code-generator的go.mod拿到的

执行完，会得到`clientset` `informers` `listers`三个目录

使用kubebuilder和code generator进行CRD开发

本文基于kubesphere v3.3.2版本解读ks-apiserver的启动及路由注册相关代码



## 启动
### 初始化
命令行框架使用cobra，在`cmd/ks-apiserver/app/server.go` 使用`NewAPIServerCommand`创建一个cobra command然后execute.

`NewAPIServerCommand`先从文件读取配置：
```go
conf, err := apiserverconfig.TryLoadFromDisk()
```
配置使用的是viper包，数据结构在`pkg/apiserver/config`定义。

然后构建一个cobra Command，将Run函数注册进去。

注册一个helper函数，用于打印命令行帮助信息。
```go
	usageFmt := "Usage:\n  %s\n"
	cols, _, _ := term.TerminalSize(cmd.OutOrStdout())
	cmd.SetHelpFunc(func(cmd *cobra.Command, args []string) {
		fmt.Fprintf(cmd.OutOrStdout(), "%s\n\n"+usageFmt, cmd.Long, cmd.UseLine())
		cliflag.PrintSections(cmd.OutOrStdout(), namedFlagSets, cols)
	})
```
添加一个version子命令，用于打印版本信息。

### Run函数
首先调用`NewAPIServer`构建一个APIServer对象（`cmd/ks-apiserver/app/options/options`），在这个函数中会把所有要用到的client对象、informer、http server以及其它的helper给创建出来，放到APIServer中。

然后调用`apiserver.PrepareRun`，这个函数主要是用来注册路由，下面详解。

最后但用`apiserver.Run`, 调用`waitForResourceSync`等待informer同步，然后启动http server.

注意Run函数的声明：
```go
func Run(s *options.ServerRunOptions, ctx context.Context) error {
```
参数里的context，是在调用时传入，这里用到了k8s社区的signals包注册信号处理：
```go
import (
	"sigs.k8s.io/controller-runtime/pkg/manager/signals
)

// ......

return Run(s, signals.SetupSignalHandler())
```
这个context会传给`apiserver.Run`, 当context close时关闭http server.

## web框架
ks-apiserver使用`"github.com/emicklei/go-restful"`框架，在这个框架中一个路由对象称为`Container`. 在apiserver的`PrepareRun`函数中（`pkg/apiserver/apiserver.go`）注册handler以及midware. 包含以下几种路由：

- `installKubesphereAPIs` 注册kubesphere自有的api
- `buildHandlerChain` -> `WithKubeAPIServer` 将/api开头的请求转发到k8s apiserver
- `buildHandlerChain` -> `WithMultipleClusterDispatcher` 将url中指定集群的请求转发过去

### kubesphere自有api
kubesphere的api在`pkg/kapis/`中定义，每一类api都会定义一个AddToContainer函数，然后在`installKubesphereAPIs`中调用，以notification为例：
```go
urlruntime.Must(notificationv1.AddToContainer(s.container, s.Config.NotificationOptions.Endpoint))
```
notification有三个版本，v1实际上没有内容，只是把请求转发到其它的版本：
```go
// there are no versions specified cause we want to proxy all versions of requests to backend service
var GroupVersion = schema.GroupVersion{Group: "notification.kubesphere.io", Version: ""}

func AddToContainer(container *restful.Container, endpoint string) error {

	proxy, err := generic.NewGenericProxy(endpoint, GroupVersion.Group, GroupVersion.Version)
	if err != nil {
		return err
	}

	return proxy.AddToContainer(container)
}
```
notification v2beta1的AddToContainer是这样的：
```go
func AddToContainer(container *restful.Container, option *nm.Options) error {
	//创建一个接口handler
	h := newHandler(option)
	//创建一个webservice，相当于一个路由group
	ws := runtime.NewWebService(GroupVersion)
	//注册路由
	ws.Route(ws.POST("/configs/notification/verification").
		Reads("").
		To(h.Verify).
		Returns(http.StatusOK, api.StatusOK, http.Response{}.Body)).
		Doc("Provide validation for notification-manager information")
	ws.Route(ws.POST("/configs/notification/users/{user}/verification").
		To(h.Verify).
		Param(ws.PathParameter("user", "user name")).
		Returns(http.StatusOK, api.StatusOK, http.Response{}.Body)).
		Doc("Provide validation for notification-manager information")
	container.Add(ws)
	return nil
}
```

### buildHandlerChain
`buildHandlerChain`函数用于给apiserver的http server添加调用链，相当于配置http中间件。添加的顺序是：
```go
//转发k8s原生api请求
handler = filters.WithKubeAPIServer(handler, s.KubernetesClient.Config(), &errorResponder{})
//审计
handler = filters.WithAuditing(handler,audit.NewAuditing(s.InformerFactory, s.Config.AuditingOptions, stopCh))
//鉴权
handler = filters.WithAuthorization(handler, authorizers)
//身份认证
handler = filters.WithAuthentication(handler, authn)
//保存请求信息到context
handler = filters.WithRequestInfo(handler, requestInfoResolver)
```
执行时，最后添加的handler会最先执行，也就是说，首先执行的是将解析请求为RequestInfo然后保存到context中。

kubesphere代码解读（一）

记录使用ddclient配置ddns的方法


# 1. 安装 docker

目前很多发行版自带的ddclient包版本都太老了，而ddclient又是c语言写的安装比较麻烦，用docker是最方便的，如果机器内存很少可以试下[nerdctl](https://github.com/containerd/nerdctl)

# 2. 使用docker-compose

`docker-compose.yaml`：
```yaml
---
services:
  ddclient:
    image: lscr.io/linuxserver/ddclient:latest
    container_name: ddclient
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Asia/Hong_Kong
    volumes:
      - /root/ddclient/config:/config
    restart: unless-stopped
```
`docker compose up -d`启动

# 3. cloudflare创建api token
待补充

# 4. 修改ddclient配置
`/root/ddclient/config/ddclient.conf`
```conf
daemon=120                              # check every 300 seconds
syslog=yes                              # log update msgs to syslog
#mail=root                              # mail all msgs to root
#mail-failure=root          # mail failed update msgs to root
pid=/var/run/ddclient/ddclient.pid      # record PID in file.
ssl=yes                                 # use ssl-support.  Works with
                                                # ssl-library
use=web, web='https://cloudflare.com/cdn-cgi/trace', web-skip='ip=' # found after IP Address
##
## CloudFlare (www.cloudflare.com)
##
protocol=cloudflare
zone=your.domain
ttl=1
login=token # Only needed if you are using your global API key. If you are using an API token, set it to "token" (wihtout double quotes).
password=your_token # This is either your global API key, or an API token. If you are using an API token, it must have the permissions "Zone - DNS - Edit" and "Zone - Zone - Read". The Zone resources must be "Include - All zones".
sub.your.domain
```
修改后重启服务

`docker compose down`  
`docker compose up -d`