Go 基础体系 · 第 101/113 篇。示例统一基于 Go 1.26.4；核心片段可能省略 package 与 import，完整程序可直接按文中结构运行。

Go Kubernetes 实战：部署、client-go Informer、Workqueue 与 Controller

本文以 Go 1.26.4、Kubernetes 1.34.1、k8s.io/client-go v0.34.1、k8s.io/api v0.34.1 和 k8s.io/apimachinery v0.34.1 为稳定基线。Kubernetes 模块按 minor 对齐，三个 Go 模块使用同一 v0.34.1，并核对客户端与集群版本兼容矩阵；生产不引用 latest。普通 Go API 只需 Deployment、Service、配置、探针和资源约束。只有当程序需要持续把 Kubernetes 资源从当前状态协调到期望状态时，才编写 Controller。

Controller 不是收到一次事件就执行一次动作的回调系统。Watch 会断、事件会合并或重复、缓存会短暂落后，进程也会在写入响应前崩溃。正确模型是 level-triggered reconcile：事件只把对象 key 放入队列，worker 每次从缓存/服务端读取当前状态，计算差异，执行幂等更新，直到收敛。

2. 部署一个 Go 服务的最小资源

Deployment 管副本与滚动更新，Service 提供稳定虚拟地址。容器监听 0.0.0.0:8080，镜像用 digest，Pod/容器安全上下文设非 root 与只读文件系统。下面省略独立 ConfigMap 内容，但不省略关键运行边界。

apiVersion: apps/v1
kind: Deployment
metadata:
  name: article-api
spec:
  replicas: 3
  strategy:
    rollingUpdate:
      maxUnavailable: 0
      maxSurge: 1
  selector:
    matchLabels: {app: article-api}
  template:
    metadata:
      labels: {app: article-api}
    spec:
      terminationGracePeriodSeconds: 40
      containers:
        - name: api
          image: registry.example.com/article@sha256:0123456789abcdef
          ports: [{name: http, containerPort: 8080}]
          envFrom: [{configMapRef: {name: article-api}}]
          resources:
            requests: {cpu: 250m, memory: 256Mi}
            limits: {memory: 512Mi}
          securityContext:
            allowPrivilegeEscalation: false
            readOnlyRootFilesystem: true
            runAsNonRoot: true
            capabilities: {drop: [ALL]}
---
apiVersion: v1
kind: Service
metadata:
  name: article-api
spec:
  selector: {app: article-api}
  ports: [{name: http, port: 80, targetPort: http}]

selector 是长期身份，修改要谨慎。request 参与调度和 HPA 利用率计算；memory limit 触发 OOM kill，CPU limit 可能产生 throttling。Go 的 GOMEMLIMIT 要低于容器 limit，为非 heap、线程、mmap 与内核开销留空间。

3. Startup、Readiness 与 Liveness 的不同承诺

Startup probe 在首次成功前保护慢启动；readiness 决定 EndpointSlice 是否接新流量；liveness 只判断进程是否陷入必须重启才能恢复的故障。把数据库短暂不可用放进 liveness 会让所有 Pod 同时重启，放大故障。

startupProbe:
  httpGet: {path: /startupz, port: http}
  periodSeconds: 2
  failureThreshold: 30
readinessProbe:
  httpGet: {path: /readyz, port: http}
  periodSeconds: 5
  timeoutSeconds: 1
livenessProbe:
  httpGet: {path: /healthz, port: http}
  periodSeconds: 10
  timeoutSeconds: 1
  failureThreshold: 3

探针 handler 必须便宜、有锁与 I/O 上限且不泄漏配置。readiness 在启动完成、配置有效、关键池可用后才成功；SIGTERM 到来先切为 false，再关闭 HTTP listener并排空。preStop 可辅助留出摘流量窗口，但应用仍必须处理信号，且 hook 时间计入 termination grace period。

6. List-Watch 为什么必须组合

只 Watch 会缺少连接前已有对象；先 List 再从资源版本 Watch 才能连续观察。Watch 连接会因超时、网络、API Server 重启、资源版本过旧或客户端太慢关闭。client-go 的 Reflector 负责 ListAndWatch、保存 resourceVersion 并重连。

resourceVersion 是并发与观察游标，不是业务版本或时间戳。服务器 compaction 后旧版本可能返回 410 Gone，Reflector 重新 List 建全量。Watch 事件包括 ADDED、MODIFIED、DELETED、BOOKMARK、ERROR；业务 handler 不应自行猜测断线恢复。

7. Reflector、DeltaFIFO、Informer 与 Indexer

SharedInformer 的内部数据路径可概括为：Reflector 把 List/Watch 变化放入 DeltaFIFO；Controller 消费 delta，一边更新本地 Store/Indexer，一边通知注册 handler；多个消费者共享同一 informer，避免每个 Controller 各自 List/Watch。

ListerWatcher -> Reflector -> DeltaFIFO -> shared informer controller
                                      |-> Indexer/cache
                                      `-> Add/Update/Delete handlers

Indexer 保存对象指针快照并可按 namespace 等索引；Lister 从缓存读取，快且不打 API Server，但可能陈旧。handler 应非常短，只提取 namespace/name key 并 queue.Add。不要在 handler 里做网络、sleep 或复杂 reconcile，否则阻塞整个 informer 事件分发。

删除可能以 cache.DeletedFinalStateUnknown tombstone 到达，因为本地缓存没见到最后对象。使用 cache.DeletionHandlingMetaNamespaceKeyFunc 正确提取 key，不能直接断言为具体资源指针。

8. 构造 SharedInformerFactory 与事件处理

Factory 可按 namespace 共享 informer。resync 不是重新 List；纯资源 Controller 通常设为 0，靠事件与显式重排。

factory := informers.NewSharedInformerFactoryWithOptions(
	clientset,
	0,
	informers.WithNamespace(namespace),
)
deploymentInformer := factory.Apps().V1().Deployments()
queue := workqueue.NewTypedRateLimitingQueue(
	workqueue.DefaultTypedControllerRateLimiter[string](),
)

_, err := deploymentInformer.Informer().AddEventHandler(
	cache.ResourceEventHandlerFuncs{
		AddFunc: func(object any) {
			key, keyErr := cache.MetaNamespaceKeyFunc(object)
			if keyErr == nil {
				queue.Add(key)
			}
		},
		UpdateFunc: func(oldObject, newObject any) {
			oldMeta := oldObject.(*appsv1.Deployment)
			newMeta := newObject.(*appsv1.Deployment)
			if oldMeta.ResourceVersion != newMeta.ResourceVersion {
				key, keyErr := cache.MetaNamespaceKeyFunc(newObject)
				if keyErr == nil {
					queue.Add(key)
				}
			}
		},
		DeleteFunc: func(object any) {
			key, keyErr := cache.DeletionHandlingMetaNamespaceKeyFunc(object)
			if keyErr == nil {
				queue.Add(key)
			}
		},
	},
)
if err != nil {
	return fmt.Errorf("add deployment event handler: %w", err)
}

生产代码应集中处理 key error；类型断言使用 comma-ok。handler 的生命周期属于 Controller。

9. Cache Sync 是启动屏障

启动顺序是注册 handler、启动 factory、等待相关 informer cache synced，再启动 worker。若未同步就 reconcile，Lister 的 not found 可能只是初始 List 尚未完成，Controller 会错误删除外部资源。

factory.Start(ctx.Done())
if synced := cache.WaitForCacheSync(
	ctx.Done(),
	deploymentInformer.Informer().HasSynced,
); !synced {
	return errors.New("deployment informer cache did not sync")
}

for range workers {
	group.Go(func() {
		for controller.processNext(ctx) {
		}
	})
}

readiness 只有在 leader 已获得、所需 cache synced、worker 已启动后才成功。初始 List 因 RBAC 或网络失败时保持 not-ready 并告警。关停先设 not-ready，取消 context，queue.ShutDown()，worker 从 Get 返回并退出，最后等待 group。

10. Workqueue 的去重与并发语义

workqueue 保存可比较 key 而不是资源对象。对象在队列等待时可能已变化，所以 worker 取 key 后总从 Lister 读最新快照。队列会合并同一个 key 的脏标记：处理期间再次 Add，Done 后会再入队；这提供最终重算，不保证每个中间事件都被逐一处理。

并发 worker 可处理不同 key，但外部副本、leader 切换和旧请求仍可能产生并行动作。因此 Reconcile 与下游副作用必须幂等。监控 depth、queue latency、work duration、retries 和最老 key 等待时间。

11. processNextItem 的正确完成协议

每次 Get 后必须 defer Done(key)。成功调用 Forget 清除 rate limiter 历史；可重试错误使用 AddRateLimited；超过预算或永久错误 Forget 并记录/写 condition。忘记 Forget 会让下次正常变化继承旧退避。

func (c *Controller) processNext(ctx context.Context) bool {
	key, shutdown := c.queue.Get()
	if shutdown {
		return false
	}
	defer c.queue.Done(key)

	err := c.reconcile(ctx, key)
	if err == nil {
		c.queue.Forget(key)
		return true
	}
	if c.queue.NumRequeues(key) < 8 && isRetryable(err) {
		c.queue.AddRateLimited(key)
		return true
	}
	c.queue.Forget(key)
	utilruntime.HandleError(fmt.Errorf("reconcile %q: %w", key, err))
	return true
}

错误在 worker 边界记录一次；reconcile 只返回带操作上下文的错误。永久 schema/权限错误无限重试只会打爆 API Server，应写失败 condition、发低频 Event 并等待 spec 或权限变化重新 Add。时间驱动状态用 AddAfter，不要为每个对象常驻 ticker goroutine。

12. 幂等 Reconcile 的读取、比较与写入

reconcile 将 key 拆成 namespace/name，从 lister 获取对象。NotFound 表示对象已删除，此时按持久外部标识清理；不能依赖已经不存在的 spec。读取缓存对象后必须 DeepCopy 再修改，因为 informer cache 对象视为只读。

func (c *Controller) reconcile(ctx context.Context, key string) error {
	namespace, name, err := cache.SplitMetaNamespaceKey(key)
	if err != nil {
		return fmt.Errorf("split resource key: %w", err)
	}
	deployment, err := c.deployments.Deployments(namespace).Get(name)
	if apierrors.IsNotFound(err) {
		return c.cleanupExternal(ctx, key)
	}
	if err != nil {
		return fmt.Errorf("get deployment from cache: %w", err)
	}

	desired := deployment.DeepCopy()
	if ensureManagedLabel(desired) == noChange {
		return nil
	}
	_, err = c.client.AppsV1().Deployments(namespace).Update(ctx, desired, metav1.UpdateOptions{})
	if err != nil {
		return fmt.Errorf("update deployment %q: %w", key, err)
	}
	return nil
}

比较应语义化，只修改 Controller 拥有字段。无变化不写，避免自触发更新循环。Update 携带 resourceVersion，冲突意味着缓存落后或其他 writer 修改；返回错误让新事件/退避重算，不要用旧对象盲重试覆盖。

14. OwnerReference、Finalizer 与删除状态机

集群内从属资源优先用 Controller OwnerReference，让垃圾回收器按 UID 关系清理。跨 namespace 和某些 scope 的 owner 关系受限制；外部云资源无法由 Kubernetes GC 删除，需要 finalizer。

创建外部资源前生成稳定外部 ID（通常来自对象 UID），重复 reconcile 查询/创建同一 ID。删除时 API Server 设置 deletionTimestamp；Controller 看到 finalizer 后执行幂等外部清理，确认目标不存在，再移除 finalizer。不能一收到 delete event 才清理，因为对象可能已从缓存消失。

normal: ensure external -> ensure finalizer -> update status
deleting: external exists -> delete/query -> remove finalizer
          external absent -----------------> remove finalizer

外部 API 不可用会让对象停在 Terminating，这是保数据的设计。设置重试、condition、告警和人工 runbook。强行移除 finalizer 可能泄漏付费资源，必须审计。

16. RBAC、ServiceAccount 与多租户安全

Controller 的 ClusterRole 只授予实际使用的 resource/verb/subresource。能 namespace 范围工作就用 Role/RoleBinding，不给 *。读取 Secret、创建 Pod、更新 status、操作 finalizer 是不同权限。leader election 还需 Lease 权限。

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: article-controller
rules:
  - apiGroups: [apps]
    resources: [deployments]
    verbs: [get, list, watch, patch, update]
  - apiGroups: [apps]
    resources: [deployments/status]
    verbs: [get, patch, update]
  - apiGroups: [coordination.k8s.io]
    resources: [leases]
    verbs: [get, create, update]

关闭不需要的 automountServiceAccountToken；Controller 必须使用时保留短期投影 token。Admission policy 限制镜像、privileged、hostPath 和资源；Controller 生成的 Pod 同样不可信，所有 CR spec 字段严格校验，不能让普通租户借 Controller 提权。

18. Context、关停与 goroutine 所有权

进程根 context 来自 SIGTERM。factory、event recorder、leader election、workers 和外部 client 都派生于明确 owner。每个 reconcile 可再加操作 deadline，但不能把短 deadline 传给 informer。context 取消不会杀 goroutine，所有 channel、HTTP、数据库和退避等待都要响应取消。

关停顺序：readiness false；停止选主/接收新业务；shutdown queue；取消 informer/watch；等待 worker；用新的短 context 刷 status/telemetry；关闭 transport。terminationGracePeriodSeconds 大于最坏排空预算。不要启动 fire-and-forget 的外部清理，可靠工作写状态后由下一轮继续。

worker 数由 API QPS、外部依赖和单次内存决定。增加副本或 worker 不应突破 client rate limiter。慢 key 不应永久占 worker，长任务改为状态机，每轮推进一步后 AddAfter。

19. 测试：Fake、反应器、Envtest 与真实集群

纯函数测试覆盖 desired diff、condition、finalizer 状态和错误分类。client-go fake 适合验证 API action，但默认 object tracker 不完整模拟 admission、defaulting、resourceVersion、SSA 和真实 watch；不要因 fake 通过就声称协议正确。Informer 测试可用 fake source 与确定性 channel，不用长 Sleep。

集成层使用 envtest（若采用 controller-runtime 测试工具）或临时真实 API Server/etcd，安装 CRD 后验证 schema、status、finalizer、冲突和 watch 恢复。Kind/Kubernetes 1.34.1 集群验证 RBAC、Deployment、probe、leader election、滚动退出和网络策略。

gofmt -w .
go test ./...
go test -race ./...
go vet ./...
go test -run TestReconcileConflict -count=100 ./...
kubectl auth can-i --as=system:serviceaccount:article:controller update deployments/status
kubectl rollout status deployment/article-controller --timeout=2m

故障测试在外部创建成功/状态写入前、finalizer 删除前、leader 切换、Watch 410、API 429 和 SIGTERM 边界终止进程。断言最终对象与外部资源收敛、重复副作用被吸收、队列排空、goroutine 无泄漏。

20. 诊断、性能与生产发布

Controller 不收敛时依次查 generation/conditions/events、leader/readiness、RBAC、cache sync、queue retry、API 429 与外部依赖。

pprof 查看 worker 阻塞与 goroutine；API Server 指标看 LIST/WATCH、延迟和 429。减少 watch 范围，用索引替代全缓存遍历；基准包含初始 List、事件风暴和外部慢调用。

发布固定 Go 1.26.4、client-go v0.34.1 和镜像 digest。CRD 先发布兼容 schema，再灰度 Controller 并观察错误、queue age 与 API QPS。

生产检查应确认：探针语义与 SIGTERM 顺序正确；request/limit 和 Go 内存预算匹配；RBAC 最小；cache sync 是启动屏障；handler 只入队；key 队列有 Forget/退避/上限；reconcile 不修改缓存对象且只写自有字段；finalizer、leader 切换和外部副作用可恢复；测试覆盖断线、冲突、重复与删除。具备这些约束，client-go 才是可靠控制循环，而不是一组容易制造集群风暴的 API 调用。

---

系列导航与关联阅读

• 系列入口：Go 完整技术体系学习路线：从语法、并发到框架、中间件与 AI
• 上一篇：Go Docker 镜像：多阶段构建、非 root、健康检查与体积
• 下一篇：Go AI 应用学习路线：LLM、RAG、Agent、MCP 与生产治理
• 延伸：Go Prometheus 与 Grafana：指标设计、埋点和告警
• 延伸：Go 服务发现与配置中心：etcd、Consul、Nacos 的正确边界
• 延伸：Go goroutine 生命周期：泄漏、打断、错误传播与优雅关闭

官方资料

• Kubernetes Go client
• Kubebuilder book
• Kubernetes application deployment

本文依据 Go 官方规范、标准库文档和 Go 官方博客重新梳理；正文与示例由 WR BLOG 编写。