Kubernetes on DK Blog

Kubernetes Pod 删除与容器重启时日志到底去哪了？

Mon, 08 Jun 2026 21:35:00 +0800

先给结论

如果只看 Kubernetes 节点本地日志，结论可以这样记：

场景	Pod 对象还在吗	本地日志是否还在	`kubectl logs` 能否查看
容器正常运行	在	在	可以，默认看当前容器日志
容器重启，Pod 还在	在	通常保留当前和上一次容器实例日志	当前日志用 `kubectl logs`，上一次用 `kubectl logs --previous`
Pod 被删除	不在	通常会被 kubelet 清理	通常不能再通过 `kubectl logs` 查看
Pod 被重建，同名但新 UID	新 Pod 在	旧 Pod 日志不会自动回来	只能看新 Pod 日志
已接入 Loki、ELK、云日志等外部系统	不一定	节点本地可能没了	可以去外部日志系统查

所以问题的直接答案是：

Pod 删除后，本地日志通常会消失。
只是容器重启、Pod 还在时，上一轮容器实例的日志通常还能通过 kubectl logs --previous 查看。

但这两个结论背后有几个容易混淆的点：Pod 名字不等于 Pod 身份，容器重启不等于 Pod 删除，0.log / 1.log 也不完全等同于“永久历史日志”。

Kubernetes 里的日志是谁在管？

大多数业务容器写日志，推荐写到标准输出和标准错误：

1
2


stdout
stderr

容器运行时会把这些输出落到节点文件系统里，kubelet 再负责管理这些容器日志文件，并通过 Kubernetes API 暴露给 kubectl logs。

也就是说，当你执行：

`1`	`kubectl logs nginx-xxx`

大致链路是：

1
2
3
4
5


kubectl
 -> apiserver
 -> kubelet
 -> 节点上的容器日志文件
 -> 返回给用户

Kubernetes 官方文档也明确说明，kubelet 默认会让容器运行时把容器日志写到 /var/log/pods 目录下，同时 kubelet 负责容器日志轮转和日志目录结构管理。

典型路径长这样：

`1`	`/var/log/pods/<namespace>_<pod-name>_<pod-uid>/<container-name>/<n>.log`

同时你经常还会看到：

`1`	`/var/log/containers/<pod-name>_<namespace>_<container-name>-<container-id>.log`

这个路径通常是指向 /var/log/pods/... 下实际日志文件的软链接，方便日志采集器按容器维度扫描。

Pod 删除后日志为什么会没？

Pod 的真实身份不是名字，而是 UID。

例如你看到的 Pod 叫：

`1`	`nginx-7c9f6d8b9d-abcde`

它在节点上的日志目录并不是只按名字组织，而是带上 Pod UID：

`1`	`/var/log/pods/default_nginx-7c9f6d8b9d-abcde_7f3c.../`

这个 UID 很关键。即使 Deployment 后面又拉起一个同名风格的新 Pod，新 Pod 也会有新的 UID，对应新的日志目录。

当 Pod 被删除后，kubelet 会逐步清理这个 Pod 在节点上的资源，包括容器、挂载目录、日志目录等。清理完成后，本地节点上的这份 Pod 日志就不再可靠可查。

所以：

`1`	`kubectl delete pod nginx-7c9f6d8b9d-abcde`

之后再执行：

`1`	`kubectl logs nginx-7c9f6d8b9d-abcde`

通常会得到类似结果：

`1`	`Error from server (NotFound): pods "nginx-7c9f6d8b9d-abcde" not found`

即使 Deployment 很快创建了一个新的 Pod，也不是原来的 Pod：

1
2


旧 Pod: nginx-7c9f6d8b9d-abcde, UID=A
新 Pod: nginx-7c9f6d8b9d-fghij, UID=B

新 Pod 的日志目录是新的，旧 Pod 的日志不会自动迁移过去。

容器重启时日志会保留吗？

会，但要加上限定条件：Pod 还在，且 kubelet / 容器运行时还没有清理对应的上一轮容器实例日志。

当 Pod 没删，只是里面的容器因为异常退出、探针失败、OOM、进程崩溃等原因重启时，Pod 还是同一个 Pod：

1
2
3


Pod UID 不变
容器实例变了
restartCount 增加

这时：

`1`	`kubectl logs <pod-name>`

看的是当前正在运行的容器实例日志。

而：

`1`	`kubectl logs <pod-name> --previous`

看的是上一次已经终止的容器实例日志。

多容器 Pod 要指定容器名：

`1`	`kubectl logs <pod-name> -c <container-name> --previous`

这就是排查 CrashLoopBackOff 时最常用的命令。因为当前容器可能刚启动，还没打印出关键错误；真正的错误通常在上一轮崩溃前的日志里。

`0.log`、`1.log` 到底怎么理解？

在节点上你可能会看到类似目录：

1
2
3


/var/log/pods/default_demo_abc123/app/
 0.log
 1.log

这很容易让人理解成：

1
2
3


0.log = 当前日志
1.log = 上一次重启日志
2.log = 上上次重启日志

这个理解在很多场景下接近现象，但不要把它当成稳定的应用层契约。

更准确的说法是：

kubelet 和容器运行时会按 CRI 日志机制维护容器日志文件。
容器重启会产生新的容器实例，上一轮实例的日志可能以另一个文件保留。
kubectl logs --previous 面向的是“上一次终止的容器实例”，不是任意历史版本。
日志文件还会受到 kubelet 日志轮转配置影响。

也就是说，你可以在节点上观察 0.log、1.log 这类文件，但日常排障不要依赖“手动猜编号”。优先使用：

1
2


kubectl logs <pod> -c <container>
kubectl logs <pod> -c <container> --previous

如果要查更久以前的日志，不应该指望节点本地文件，而应该依赖外部日志系统。

还有一种“轮转”：不是重启，而是文件太大

容器一直不重启，日志文件也不可能无限增长。kubelet 会对容器日志做轮转。

常见默认值是：

1
2


containerLogMaxSize: 10Mi
containerLogMaxFiles: 5

含义是：

单个容器日志文件达到一定大小后会触发轮转
每个容器最多保留一定数量的日志文件

这和“容器重启产生上一轮日志”不是同一个概念。

可以把它们分开理解：

类型	触发条件	目的
容器实例切换	容器退出后被 kubelet 重新拉起	让当前实例和上一轮实例日志可区分
日志大小轮转	单个日志文件达到上限	防止节点磁盘被日志打满

官方文档也提醒：通过 kubectl logs 通常只能拿到最新日志文件的内容。如果容器写了很多日志，旧的轮转文件不一定会通过普通 kubectl logs 全量返回。

所以不要误以为：

`1`	`kubectl logs <pod>`

一定能拿到容器从启动到现在的所有日志。它拿到的是 kubelet 当前能通过日志接口返回的内容。

三个典型场景

场景一：Deployment 滚动发布

Deployment 发布新版本时，旧 ReplicaSet 下的 Pod 会被逐步删除，新版本 Pod 会被创建。

这个过程不是“容器重启”，而是：

1
2


旧 Pod 删除
新 Pod 创建

结果是：

旧 Pod 本地日志会随 Pod 清理而消失
新 Pod 是新 UID，只能看到新日志
想查旧版本发布前后的日志，必须依赖外部日志系统

如果线上问题发生在发布瞬间，只靠 kubectl logs 很容易错过现场。

场景二：CrashLoopBackOff

容器反复崩溃，但 Pod 对象还在。

这时不要只看：

`1`	`kubectl logs <pod>`

还要看：

`1`	`kubectl logs <pod> --previous`

如果是多容器：

`1`	`kubectl logs <pod> -c <container> --previous`

排查顺序建议是：

1
2
3
4


kubectl describe pod <pod>
kubectl logs <pod> -c <container>
kubectl logs <pod> -c <container> --previous
kubectl get pod <pod> -o jsonpath='{.status.containerStatuses[*].restartCount}'

describe 看事件和退出原因，logs --previous 看上一轮进程退出前的业务日志。

场景三：节点磁盘被日志打满

如果业务疯狂输出日志，Pod 不删除、不重启，节点磁盘也可能被打满。

这时要关注：

kubelet 的 containerLogMaxSize
kubelet 的 containerLogMaxFiles
节点 /var/log/pods 和 /var/log/containers 使用量
日志采集器是否及时采集并上报
是否有应用把日志写进容器文件系统或 emptyDir

生产环境里，容器 stdout/stderr 只适合作为采集入口，不适合作为长期存储。

为什么“Pod 删除日志就没了”是合理设计？

Kubernetes 的设计重点是调度和编排，不是日志长期存储。

Pod 是临时对象，可能因为很多原因消失：

Deployment 滚动发布
节点驱逐
HPA 缩容
Job 执行完成
手动删除
节点故障
镜像升级

如果 Kubernetes 默认把每个已经删除的 Pod 日志都长期保存在节点上，会带来几个问题：

节点磁盘不可控
Pod 被调度到不同节点后日志分散
节点故障时日志仍然可能丢
多租户环境下清理和隔离更复杂

所以 Kubernetes 只提供基本日志访问能力。真正的“日志持久化”和“跨 Pod 查询”应该交给集群级日志系统。

生产环境应该怎么做？

如果日志有排障、审计、交易链路追踪等价值，不要依赖节点本地日志。

推荐做法是接入集群级日志采集：

1
2
3
4
5


应用 stdout/stderr
 -> /var/log/pods
 -> 节点日志采集 DaemonSet
 -> Loki / Elasticsearch / OpenSearch / 云日志服务
 -> 查询、告警、归档

常见方案：

Fluent Bit / Fluentd
Vector
Filebeat
Promtail + Loki
OpenTelemetry Collector
云厂商托管日志服务

关键原则：

应用日志写 stdout/stderr
节点上部署 DaemonSet 采集器
日志进入远端存储后再做查询和告警
本地日志只当短期缓冲，不当长期存储

常用命令整理

查看当前容器日志：

`1`	`kubectl logs <pod>`

查看指定容器日志：

`1`	`kubectl logs <pod> -c <container>`

查看上一次终止的容器实例日志：

`1`	`kubectl logs <pod> -c <container> --previous`

查看 Pod 事件和容器退出原因：

`1`	`kubectl describe pod <pod>`

查看重启次数：

1

kubectl get pod <pod> -o jsonpath='{.status.containerStatuses[*].restartCount}'

查看 Pod UID：

1

kubectl get pod <pod> -o jsonpath='{.metadata.uid}'

在节点上观察日志目录：

1
2


ls -lah /var/log/pods/
ls -lah /var/log/containers/

查看 kubelet 日志轮转配置，具体路径取决于集群安装方式：

1

cat /var/lib/kubelet/config.yaml | grep -E 'containerLogMaxSize|containerLogMaxFiles'

最后总结

这两个问题可以这样回答：

Pod 删除，日志通常就没了。

因为 Pod 删除后 kubelet 会清理该 Pod 在节点上的相关资源，本地 /var/log/pods/<namespace>_<pod>_<uid>/ 不应被当成持久化日志存储。后续即使出现同名 Pod，也已经是新 UID、新日志目录。

容器只是重启，上一轮日志通常还能看。

因为 Pod 还在，kubelet 通常会保留上一轮终止容器实例的日志，可以通过：

`1`	`kubectl logs <pod> --previous`

查看。但它不是完整历史日志系统，也不是无限保留。它受容器实例生命周期、kubelet 清理策略和日志轮转配置影响。

真正可靠的结论是：kubectl logs 适合临时排障，生产环境日志留存必须依赖外部日志系统。

参考资料

Kubernetes 官方文档：Logging Architecture
Kubernetes 官方文档：kubectl logs
Kubernetes 官方文档：kubelet 参数

Pod Pending 排查：不是所有 Pending 都是资源不够

Sat, 14 Mar 2026 11:08:00 +0800

Pod Pending 很容易被一句“资源不够”带过去。但实际排查下来，Pending 只是说明 Pod 还没有被成功调度到节点上，原因可能很多。

我现在遇到 Pending，基本不会先猜，先看 Events。

我会把 Pending 当成“调度器没有找到合适节点”的结果，而不是根因。这个视角很重要，因为资源不足只是其中一种，更多时候是自己写的约束互相打架。

第一步：describe Pod

1
2
3


kubectl get pod -n default

kubectl describe pod -n default api-server-xxx

重点看最后的 Events，特别是 FailedScheduling。

也可以直接按时间看事件：

1
2
3
4
5


kubectl get events -n default --sort-by=.lastTimestamp

kubectl get events -n default \
 --field-selector involvedObject.kind=Pod,involvedObject.name=api-server-xxx \
 --sort-by=.lastTimestamp

如果看到类似：

1
2


Warning FailedScheduling default-scheduler 0/3 nodes are available:
3 Insufficient cpu.

那确实是资源问题。但如果看到的是 affinity、taint、PVC、topology spread，就要换方向查。

我会先把 Events 里的原因按类型拆一下：

Event 关键词	优先看什么
`Insufficient cpu/memory`	requests、节点 allocatable、是否有过大副本
`node affinity/selector`	nodeSelector、nodeAffinity、节点 label
`taint`	node taints、Pod tolerations
`pod anti-affinity`	副本数、topologyKey、已有 Pod 分布
`unbound immediate PersistentVolumeClaims`	PVC、StorageClass、PV、provisioner
`topology spread`	maxSkew、topology label、whenUnsatisfiable

CPU 或内存 request 太大

比如这个 Pod 请求了 4 核 CPU：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


apiVersion: v1
kind: Pod
metadata:
 name: big-request
spec:
 containers:
 - name: app
 image: nginx:1.27
 resources:
 requests:
 cpu: "4"
 memory: 4Gi

如果集群里没有任何一个节点能提供这么多可分配资源，它就会 Pending。

1
2
3
4
5


kubectl describe pod big-request

kubectl describe node node-1

kubectl top node

要注意，调度看的是 request，不是当前真实使用量。一个节点 top 看起来还有空闲，不代表它还能接收新的大 request Pod。

nodeSelector 或 nodeAffinity 匹配不到节点

比如 Pod 要求只能跑到 disk=ssd 的节点：

1
2
3


spec:
 nodeSelector:
 disk: ssd

但节点根本没有这个 label：

`1`	`kubectl get nodes -L disk`

那就会调度失败。

nodeAffinity 也是一样：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


spec:
 affinity:
 nodeAffinity:
 requiredDuringSchedulingIgnoredDuringExecution:
 nodeSelectorTerms:
 - matchExpressions:
 - key: node-pool
 operator: In
 values:
 - online

如果是 required，匹配不到就不会调度。preferred 只是偏好，不会单独导致 Pending。

节点有 taint，但 Pod 没有 toleration

节点可以通过 taint 排斥 Pod。

1

kubectl taint nodes node-1 dedicated=gpu:NoSchedule

没有对应 toleration 的 Pod 不会被调度到这个节点。

查看节点 taint：

1

kubectl describe node node-1 | grep -i taints

给 Pod 加 toleration：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


apiVersion: v1
kind: Pod
metadata:
 name: tolerate-gpu-node
spec:
 tolerations:
 - key: "dedicated"
 operator: "Equal"
 value: "gpu"
 effect: "NoSchedule"
 containers:
 - name: app
 image: nginx:1.27

还有一类自动 taint 也很常见，比如节点出现 DiskPressure、MemoryPressure、NotReady 时，控制面会给节点加对应 taint。

PVC 没有绑定

有些 Pod Pending 不是因为 CPU，也不是因为 affinity，而是 PVC 还没有 Bound。

1
2


kubectl get pvc -n default
kubectl describe pvc data -n default

如果 PVC 一直 Pending，常见方向是：

没有默认 StorageClass。
PVC 指定的 storageClassName 不存在。
请求容量太大，没有匹配的 PV。
动态 provisioner 异常。
local PV 带 nodeAffinity，限制了可调度节点。

PVC 不 Bound 时，Pod 可能一直等着，看起来像调度问题，但根因在存储。

存储这里还有个细节：有些 StorageClass 使用 WaitForFirstConsumer，PVC 不会立刻 Bound，而是等 Pod 调度时一起考虑拓扑。这个场景下 PVC Pending 不一定是坏事，要结合 StorageClass 的 volumeBindingMode 看。

anti-affinity 或 topologySpreadConstraints 太硬

例如强制同一个应用不能在同一个节点：

1
2
3
4
5
6
7


affinity:
 podAntiAffinity:
 requiredDuringSchedulingIgnoredDuringExecution:
 - labelSelector:
 matchLabels:
 app: api-server
 topologyKey: kubernetes.io/hostname

如果只有 2 个节点，却要 3 个副本，第 3 个副本就没有位置。

topologySpreadConstraints 也类似：

1
2
3
4
5
6
7


topologySpreadConstraints:
 - maxSkew: 1
 topologyKey: topology.kubernetes.io/zone
 whenUnsatisfiable: DoNotSchedule
 labelSelector:
 matchLabels:
 app: api-server

如果只是希望尽量分散，不想因为分布不均导致 Pending，可以考虑把 DoNotSchedule 改成 ScheduleAnyway，或者放宽 maxSkew。

一个固定排查顺序

我一般按这个顺序来：

1
2
3
4
5
6
7


kubectl describe pod <pod> -n <ns>
kubectl get events -n <ns> --sort-by=.lastTimestamp
kubectl get nodes -o wide
kubectl get nodes --show-labels
kubectl describe node <node>
kubectl get pvc -n <ns>
kubectl describe pvc <pvc> -n <ns>

如果 Events 里已经明确写了 FailedScheduling 的原因，就优先相信 Events。Pending 不是一个根因，它只是结果。真正要找的是调度器为什么找不到合适节点。

如果排查到最后发现多个原因同时存在，我会先处理“硬约束”。比如先解决 PVC、taint、required nodeAffinity，再看资源和 preferred 规则。软约束通常不是 Pending 的直接原因，硬约束才是。

参考资料

Kubernetes HPA 扩缩容不符合预期时怎么查

Wed, 21 Jan 2026 20:37:00 +0800

HPA 看起来配置很简单：CPU 超过多少就扩容，低于多少就缩容。但真正出问题时，经常不是 HPA 本身坏了，而是指标、requests、readiness、稳定窗口这些东西一起影响了结果。

我一般按下面的顺序查。

我遇到过最典型的误判是：业务说“CPU 都 80% 了为什么不扩容”，结果看的是节点 CPU 或容器 limit，而 HPA 算的是当前使用量相对于 requests 的 utilization。指标口径没对齐时，后面所有判断都会偏。

先看 HPA 当前状态

1
2
3


kubectl get hpa -n default

kubectl describe hpa api-server -n default

kubectl get hpa 里重点看：

TARGETS 有没有显示 <unknown>。
MINPODS、MAXPODS 是否符合预期。
REPLICAS 是当前副本数还是已经被限制住了。

describe hpa 里重点看 Conditions 和 Events。比如指标拿不到、目标对象无法 scale、已经达到 maxReplicas、缩容被稳定窗口延迟。

确认 metrics-server 正常

CPU、内存这类 resource metrics 通常依赖 metrics.k8s.io，一般由 metrics-server 提供。

1
2
3
4
5
6


kubectl get apiservice v1beta1.metrics.k8s.io

kubectl describe apiservice v1beta1.metrics.k8s.io

kubectl top node
kubectl top pod -n default

如果这里都拿不到数据，HPA 大概率也拿不到。不要一上来改 HPA YAML。

CPU utilization 依赖 requests

这是 HPA 排查里很常见的坑。

如果 HPA 用的是 CPU utilization：

1
2
3
4
5
6
7


metrics:
 - type: Resource
 resource:
 name: cpu
 target:
 type: Utilization
 averageUtilization: 60

这里的 60% 不是“宿主机 CPU 的 60%”，而是 Pod 当前 CPU 使用量相对于 container resources.requests.cpu 的比例。

换成公式大概就是：

1
2


current utilization = current CPU usage / requests.cpu
desired replicas = ceil(current replicas * current utilization / target utilization)

真实实现还会考虑缺失指标、未 Ready Pod、容忍区间和稳定窗口，但这个公式能帮人先把口径对齐。

所以 Deployment 里需要有 requests：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


apiVersion: apps/v1
kind: Deployment
metadata:
 name: api-server
spec:
 selector:
 matchLabels:
 app: api-server
 template:
 metadata:
 labels:
 app: api-server
 spec:
 containers:
 - name: api-server
 image: nginx:1.27
 resources:
 requests:
 cpu: 200m
 memory: 256Mi
 limits:
 cpu: 1000m
 memory: 512Mi

更稳一点可以用 jsonpath 看 requests：

1
2


kubectl get deploy api-server -n default \
 -o jsonpath='{range .spec.template.spec.containers[*]}{.name}{" requests="}{.resources.requests}{"\n"}{end}'

一个完整的 HPA 示例

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42


apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
 name: api-server
spec:
 scaleTargetRef:
 apiVersion: apps/v1
 kind: Deployment
 name: api-server
 minReplicas: 2
 maxReplicas: 10
 metrics:
 - type: Resource
 resource:
 name: cpu
 target:
 type: Utilization
 averageUtilization: 60
 - type: Resource
 resource:
 name: memory
 target:
 type: Utilization
 averageUtilization: 75
 behavior:
 scaleUp:
 stabilizationWindowSeconds: 0
 policies:
 - type: Percent
 value: 100
 periodSeconds: 60
 - type: Pods
 value: 4
 periodSeconds: 60
 selectPolicy: Max
 scaleDown:
 stabilizationWindowSeconds: 300
 policies:
 - type: Percent
 value: 30
 periodSeconds: 60
 selectPolicy: Max

maxReplicas 是硬上限。指标再高，也不会超过这个值。

多个 metrics 同时配置时，HPA 会分别计算期望副本数，然后取最大的那个。

scaleDown.stabilizationWindowSeconds: 300 表示缩容会参考过去一段时间的建议值，避免指标刚降下来就马上删 Pod。

为什么负载下来了还不缩容

常见原因：

还在 scale down stabilization window 内。
某个指标仍然建议较高副本数。
metrics 获取失败，HPA 为了保守跳过缩容。
minReplicas 限制住了。
Deployment 还在 rollout，观察值不稳定。

Kubernetes 默认的 scale down 稳定窗口是 300 秒。不要期待请求量一掉下来副本马上减少。

这其实是好事。缩容太快会把刚恢复的系统再次打抖，尤其是有连接池、缓存预热、JVM 或大模型服务这种启动成本时。很多时候我们抱怨“不缩容”，其实是 HPA 在帮你避免频繁震荡。

为什么负载上来了也不扩容

我会按这个顺序查：

1
2
3
4
5


kubectl top pod -n default -l app=api-server

kubectl describe hpa api-server -n default

kubectl get deploy api-server -n default -o jsonpath='{.status.readyReplicas}{" / "}{.status.replicas}{"\n"}'

常见原因是指标没拿到、CPU request 没配、还没超过容忍区间、Pod 还没 Ready，或者已经到 maxReplicas 了。

我会额外看一个细节：当前是否正在 rollout。新 Pod 还没稳定 Ready 时，HPA 的观测和 Deployment 的滚动发布会互相影响。这个时候不要急着同时改 HPA、改 requests、改镜像版本，否则最后很难判断到底是哪一个动作生效。

如果一个 Deployment 已经被 HPA 管理，我倾向于不要在日常 apply 的 manifest 里固定写死 spec.replicas。否则每次 apply 都可能把副本数改回 YAML 里的值，和 HPA 的调整互相打架。

排查 HPA 不要只盯着 HPA YAML。真正有用的信息通常分散在 metrics-server、Pod requests、HPA Conditions、Deployment rollout 状态和 readiness 里。

参考资料

Pod 为什么没有按预期分散？从 anti-affinity 到 topologySpreadConstraints

Sat, 06 Dec 2025 22:14:00 +0800

有次看一个服务的副本分布，Deployment 配了 6 个副本，预期是每个节点差不多分一点。但实际看下来，有两个节点各跑了 2 个，有的节点一个都没有。

第一反应是加 podAntiAffinity，但后来发现这个场景更适合 topologySpreadConstraints。

这里的关键不是“能不能分散”，而是“分散到什么程度算可以接受”。anti-affinity 表达的是排斥关系，topology spread 表达的是倾斜度。前者更像硬规则，后者更像分布预算。

先确认实际分布

先不要改 YAML，先看当前 Pod 落点：

1
2
3


kubectl get pod -n default -l app=web -o wide

kubectl get nodes -L kubernetes.io/hostname,topology.kubernetes.io/zone

如果 Pod 已经 Pending，再看调度事件：

`1`	`kubectl describe pod -n default web-xxx`

anti-affinity 能解决什么

最直接的写法是用 podAntiAffinity，让同一个应用的 Pod 不要放在同一个节点：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


apiVersion: apps/v1
kind: Deployment
metadata:
 name: web
spec:
 replicas: 3
 selector:
 matchLabels:
 app: web
 template:
 metadata:
 labels:
 app: web
 spec:
 affinity:
 podAntiAffinity:
 requiredDuringSchedulingIgnoredDuringExecution:
 - labelSelector:
 matchLabels:
 app: web
 topologyKey: kubernetes.io/hostname
 containers:
 - name: web
 image: nginx:1.27

这个配置比较硬：同一个节点上不能有两个 app=web 的 Pod。

它适合副本数小于等于可用节点数的场景。比如 3 个节点跑 3 个副本，很干净。

但如果 replicas 是 6，集群只有 3 个节点，后面 3 个 Pod 就会 Pending。因为 hard anti-affinity 已经把节点都排除掉了。

所以很多时候我不会直接上 required，而是先用 preferred：

1
2
3
4
5
6
7
8
9


affinity:
 podAntiAffinity:
 preferredDuringSchedulingIgnoredDuringExecution:
 - weight: 100
 podAffinityTerm:
 labelSelector:
 matchLabels:
 app: web
 topologyKey: kubernetes.io/hostname

这个配置会让调度器尽量分散，但它不是强保证。资源紧张的时候，还是可能放在一起。

topologySpreadConstraints 更像控制倾斜度

如果目标不是“绝对不能放一起”，而是“尽量均匀”，topologySpreadConstraints 更合适。

比如希望 app=web 按节点均匀分布：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


apiVersion: apps/v1
kind: Deployment
metadata:
 name: web
spec:
 replicas: 6
 selector:
 matchLabels:
 app: web
 template:
 metadata:
 labels:
 app: web
 spec:
 topologySpreadConstraints:
 - maxSkew: 1
 topologyKey: kubernetes.io/hostname
 whenUnsatisfiable: DoNotSchedule
 labelSelector:
 matchLabels:
 app: web
 containers:
 - name: web
 image: nginx:1.27

几个字段的理解：

topologyKey：按哪个节点 label 划分拓扑域。按节点分散一般用 kubernetes.io/hostname，按可用区分散一般用 topology.kubernetes.io/zone。
labelSelector：统计哪些 Pod。这里统计同一个应用 app=web。
maxSkew：允许的最大倾斜度。设为 1 时，调度器会尽量让不同拓扑域之间的匹配 Pod 数量差距不超过 1。
whenUnsatisfiable：不能满足时怎么办。DoNotSchedule 表示不调度，ScheduleAnyway 表示仍然调度，但优先选择能降低倾斜的节点。

maxSkew 很容易被误解。它不是“每个节点最多几个 Pod”，而是不同拓扑域之间的数量差距。比如 3 个节点跑 7 个副本，maxSkew: 1 的理想结果大概是 3/2/2，不是每个节点只能跑 1 个。

如果更关心可用区，而不是节点，可以这样写：

1
2
3
4
5
6
7


topologySpreadConstraints:
 - maxSkew: 1
 topologyKey: topology.kubernetes.io/zone
 whenUnsatisfiable: DoNotSchedule
 labelSelector:
 matchLabels:
 app: web

这要求节点必须有 topology.kubernetes.io/zone 这个 label。排查时可以直接看：

`1`	`kubectl get nodes -L topology.kubernetes.io/zone`

怎么选

如果诉求是“同一个节点绝对不能放两个副本”，用 hard podAntiAffinity。

如果诉求是“尽量均匀，不要太偏”，优先用 topologySpreadConstraints。

如果集群节点数不固定，服务还会扩缩容，topologySpreadConstraints 通常更好维护。因为它表达的是分布倾斜度，而不是简单地排斥某个拓扑域。

一个容易踩的坑是 labelSelector 没匹配到自己。topologySpreadConstraints 的 labelSelector 要能匹配 Pod template 里的 labels。否则调度器统计的就不是你以为的那组 Pod。

还有一个排查点是节点缺 topology label。比如你按 topology.kubernetes.io/zone 分散，但某些节点没有这个 label，结果就会很奇怪。生产里最好把节点标签一致性当成集群初始化的一部分，而不是等 Pending 以后再补。

改完后我一般这样看：

1
2
3
4
5


kubectl rollout restart deployment/web -n default
kubectl rollout status deployment/web -n default

kubectl get pod -n default -l app=web -o wide
kubectl describe pod -n default -l app=web

如果还是 Pending，直接看 Events。对于拓扑分布来说，Pending 不一定是资源不够，也可能是 maxSkew 太小、DoNotSchedule 太硬、节点缺 topology label，或者多个约束叠加后没有节点能满足。

我现在的默认倾向是：关键服务节点级别可以用 DoNotSchedule，可用区级别先用 ScheduleAnyway。除非业务真的不能接受某个 zone 副本偏多，否则不要让一个分布策略直接阻断发布。

参考资料

Kubernetes 亲和性与反亲和性配置记录

Sat, 18 Oct 2025 09:26:00 +0800

最近看一个服务的调度配置，发现它同时用了 nodeSelector、nodeAffinity 和 podAntiAffinity。表面上看是“让服务跑到指定节点池，并尽量分散”，但真正排查 Pending 的时候，发现这些规则叠在一起以后不太直观。

这篇简单记录一下我自己看调度规则时的判断顺序。

我一开始看错的地方是：以为 preferred 写了就一定会分散，后来才意识到它只是调度器打分时的偏好。只要资源、污点、PVC 或其他硬条件把节点集合压小，软亲和性很容易被牺牲。

先看节点标签

亲和性本质上还是围绕 label 做匹配。排查前先看节点上到底有没有这些 label：

1
2
3
4
5
6


kubectl get nodes --show-labels

kubectl get nodes \
 -L kubernetes.io/os \
 -L node-role.kubernetes.io/worker \
 -L topology.kubernetes.io/zone

如果 YAML 里写了 topology.kubernetes.io/zone，但节点上根本没有这个 label，后面分析半天都是偏的。

nodeSelector 和 nodeAffinity

nodeSelector 比较直接，只能做简单的等值匹配：

1
2
3


spec:
 nodeSelector:
 node-role.kubernetes.io/worker: "true"

nodeAffinity 更灵活，可以写 In、NotIn、Exists、DoesNotExist、Gt、Lt 这些操作符，也可以区分硬约束和软约束。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36


apiVersion: apps/v1
kind: Deployment
metadata:
 name: api-server
spec:
 replicas: 3
 selector:
 matchLabels:
 app: api-server
 template:
 metadata:
 labels:
 app: api-server
 spec:
 affinity:
 nodeAffinity:
 requiredDuringSchedulingIgnoredDuringExecution:
 nodeSelectorTerms:
 - matchExpressions:
 - key: node-role.kubernetes.io/worker
 operator: Exists
 - key: kubernetes.io/os
 operator: In
 values:
 - linux
 preferredDuringSchedulingIgnoredDuringExecution:
 - weight: 80
 preference:
 matchExpressions:
 - key: topology.kubernetes.io/zone
 operator: In
 values:
 - cn-east-1a
 containers:
 - name: api-server
 image: nginx:1.27

requiredDuringSchedulingIgnoredDuringExecution 是硬条件，不满足就不会调度。preferredDuringSchedulingIgnoredDuringExecution 是软条件，调度器会尽量满足，但不满足也可以调度。

IgnoredDuringExecution 的意思是：Pod 已经调度成功后，如果节点 label 后面变了，Kubernetes 不会因为这个亲和性规则把 Pod 赶走。

还有一个容易忽略的点：如果同时写了 nodeSelector 和 nodeAffinity，它们都必须满足。不是二选一。

多个 nodeSelectorTerms 之间是 OR，只要满足其中一个 term 就可以。同一个 term 里的多个 matchExpressions 是 AND，必须全部满足。

我通常会把它翻译成一行布尔表达式再看：

1
2
3
4
5
6
7
8
9


nodeSelector
AND
(term1.expressionA AND term1.expressionB OR term2.expressionC)
AND
pod anti-affinity hard rules
AND
taints/tolerations
AND
resources

这么写出来以后，很多 Pending 就不神秘了。不是 Kubernetes 调度器“抽风”，而是自己把可用节点交集写没了。

podAffinity 和 podAntiAffinity

podAffinity 不是看节点 label，而是看“某个拓扑域里有没有符合 label 的 Pod”。

比如希望业务 Pod 尽量跟缓存 Pod 在同一个可用区，减少跨可用区访问：

1
2
3
4
5
6
7


affinity:
 podAffinity:
 requiredDuringSchedulingIgnoredDuringExecution:
 - labelSelector:
 matchLabels:
 app: redis
 topologyKey: topology.kubernetes.io/zone

这个规则要小心。如果 redis 本身还没起来，或者 redis 不在当前 namespace，新的业务 Pod 就可能 Pending。podAffinity 默认只匹配当前 namespace，如果要跨 namespace，需要显式写 namespaces 或 namespaceSelector。

更常见的是 podAntiAffinity，比如同一个 Deployment 的多个副本尽量不要落在同一个节点：

1
2
3
4
5
6
7
8
9


affinity:
 podAntiAffinity:
 preferredDuringSchedulingIgnoredDuringExecution:
 - weight: 100
 podAffinityTerm:
 labelSelector:
 matchLabels:
 app: api-server
 topologyKey: kubernetes.io/hostname

这里用的是 preferred，所以只是尽量分散。如果节点资源紧张，多个 Pod 仍然可能被放到同一个节点。

这个配置看起来短，但里面有几个字段不能只按字面理解。

weight: 100 只在 preferredDuringSchedulingIgnoredDuringExecution 里出现，范围是 1 到 100。它不是“强制程度”，而是调度器打分时这个偏好的权重。多个 preferred 规则同时存在时，调度器会把满足偏好的节点加分，最后选择综合分数更高的节点。也就是说，weight: 100 仍然是软偏好，不会让 Pod Pending。

podAffinityTerm 才是真正描述“跟谁保持距离”的规则。它至少要看三个东西：

labelSelector：选择已有 Pod。
topologyKey：定义“同一个拓扑域”。
namespaces / namespaceSelector：决定跨不跨 namespace 查已有 Pod。

topologyKey: kubernetes.io/hostname 的意思不是“按节点名匹配 Pod label”，而是看节点上这个 label 的值。通常每个节点的 kubernetes.io/hostname 不同，所以效果就是“尽量不要放到同一个节点”。如果换成 topology.kubernetes.io/zone，含义就变成“尽量不要放到同一个可用区”。

这个差别很大：

1
2
3


kubernetes.io/hostname 节点级分散
topology.kubernetes.io/zone 可用区级分散
topology.kubernetes.io/region 地域级分散，通常不这么用

如果只是想让副本分散到不同节点，用 hostname 就够了。如果想跨可用区做容灾，要用 zone，但这时候更推荐一起评估 topologySpreadConstraints，因为它表达“分布倾斜度”会更直观。

如果要强制分散，可以写成 required：

1
2
3
4
5
6
7


affinity:
 podAntiAffinity:
 requiredDuringSchedulingIgnoredDuringExecution:
 - labelSelector:
 matchLabels:
 app: api-server
 topologyKey: kubernetes.io/hostname

如果集群只有 2 个可用节点，但 Deployment 要 3 个副本，第 3 个 Pod 很可能 Pending。

大集群里还要注意性能。官方文档提醒 inter-pod affinity/anti-affinity 在大规模集群中可能拖慢调度，因为调度器需要跨节点检查已有 Pod 的标签和拓扑域。简单说，节点和 Pod 越多，这类规则越不便宜。能用 topologySpreadConstraints 表达“均匀分布”的场景，我会优先考虑它。

还有一个准入层面的细节：对于 requiredDuringSchedulingIgnoredDuringExecution 的 Pod anti-affinity，Kubernetes 默认的 LimitPodHardAntiAffinityTopology 准入控制器会把 topologyKey 限制为 kubernetes.io/hostname。也就是说，hard anti-affinity 想直接用 zone 做强约束，可能会被准入策略拦住。这个限制是为了避免过重、过宽的硬反亲和规则影响调度。

podAntiAffinity 里容易漏掉的配置

上面的例子只用了 matchLabels，实际项目里经常不够。

matchExpressions：不要只会 matchLabels

如果同一个服务有多个组件，不想跟某几类组件混在一起，可以用 matchExpressions：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


affinity:
 podAntiAffinity:
 preferredDuringSchedulingIgnoredDuringExecution:
 - weight: 80
 podAffinityTerm:
 labelSelector:
 matchExpressions:
 - key: app
 operator: In
 values:
 - api-server
 - key: component
 operator: NotIn
 values:
 - canary
 topologyKey: kubernetes.io/hostname

这个规则的意思是：调度当前 Pod 时，尽量避开已经运行了 app=api-server 且 component 不是 canary 的节点。

matchLabels 和 matchExpressions 是 AND 关系，不是 OR。这个点很容易写错。如果你既写了：

1
2
3
4
5
6
7


matchLabels:
 app: api-server
matchExpressions:
 - key: component
 operator: In
 values:
 - stable

那它匹配的是 app=api-server AND component in (stable)。

namespaces / namespaceSelector：默认只看当前 namespace

podAffinityTerm 默认只匹配当前 Pod 所在 namespace 里的 Pod。这个默认行为有时候会让人误判。

比如你有两个 namespace：

1
2


prod-a/api-server
prod-b/api-server

如果你希望两个 namespace 的 api-server 也不要落到同一个节点，必须显式指定 namespace：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


affinity:
 podAntiAffinity:
 requiredDuringSchedulingIgnoredDuringExecution:
 - labelSelector:
 matchLabels:
 app: api-server
 namespaces:
 - prod-a
 - prod-b
 topologyKey: kubernetes.io/hostname

如果 namespace 很多，用 namespaceSelector 更合适。比如只匹配带有 tenant=prod 标签的 namespace：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


affinity:
 podAntiAffinity:
 preferredDuringSchedulingIgnoredDuringExecution:
 - weight: 100
 podAffinityTerm:
 labelSelector:
 matchLabels:
 app: api-server
 namespaceSelector:
 matchLabels:
 tenant: prod
 topologyKey: kubernetes.io/hostname

这里要先给 namespace 打标签：

1
2


kubectl label namespace prod-a tenant=prod
kubectl label namespace prod-b tenant=prod

如果 namespaces 和 namespaceSelector 同时写，匹配范围是两者的并集。都不写时，就是当前 Pod 的 namespace。

matchLabelKeys：跟当前 Pod 的标签值绑定

Kubernetes 还支持 matchLabelKeys。它会从“当前正在调度的 Pod”上取指定 key 的 value，再和 labelSelector 合并。

这个字段适合 Deployment 滚动发布时使用，避免新旧 ReplicaSet 的 Pod 互相干扰。比如不同 revision 的 Pod 都有 pod-template-hash：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


affinity:
 podAntiAffinity:
 preferredDuringSchedulingIgnoredDuringExecution:
 - weight: 100
 podAffinityTerm:
 labelSelector:
 matchLabels:
 app: api-server
 matchLabelKeys:
 - pod-template-hash
 topologyKey: kubernetes.io/hostname

含义是：不仅要匹配 app=api-server，还要拿当前 Pod 的 pod-template-hash 值去匹配已有 Pod。这样调度器更关注同一个 rollout revision 的 Pod 分布，而不是把历史 revision 也算进去。

这个配置比简单的 app=api-server 更细，尤其适合滚动发布时避免新旧版本互相影响调度判断。

mismatchLabelKeys：租户隔离时更有用

mismatchLabelKeys 是另一个容易忽略的字段。它会从当前 Pod 标签里取 key 的值，然后匹配“这个 key 的值不相同”的已有 Pod。

一个典型场景是多租户隔离：不要把不同 tenant 的 Pod 放到同一个节点池或同一个节点。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


affinity:
 podAntiAffinity:
 requiredDuringSchedulingIgnoredDuringExecution:
 - mismatchLabelKeys:
 - tenant
 labelSelector:
 matchExpressions:
 - key: tenant
 operator: Exists
 topologyKey: kubernetes.io/hostname

假设当前 Pod 是 tenant=team-a，这个规则会让它排斥同一 hostname 上已有的 tenant!=team-a 的 Pod。

这个字段不要随便用在经常变的 label 上。官方文档也提醒，不要对调度后还可能直接修改的 label 使用这类动态匹配字段，否则 kubelet 不会因为 label 后续变化而重新触发调度。

一个更完整的 Deployment 例子

如果我要给一个生产 API 写“尽量分散，但不要因为节点不足卡死”的配置，会更像这样：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37


apiVersion: apps/v1
kind: Deployment
metadata:
 name: api-server
 namespace: prod-a
spec:
 replicas: 4
 selector:
 matchLabels:
 app: api-server
 template:
 metadata:
 labels:
 app: api-server
 tenant: team-a
 spec:
 affinity:
 podAntiAffinity:
 preferredDuringSchedulingIgnoredDuringExecution:
 - weight: 100
 podAffinityTerm:
 labelSelector:
 matchLabels:
 app: api-server
 namespaceSelector:
 matchLabels:
 tenant: prod
 topologyKey: kubernetes.io/hostname
 - weight: 50
 podAffinityTerm:
 labelSelector:
 matchLabels:
 app: api-server
 topologyKey: topology.kubernetes.io/zone
 containers:
 - name: api-server
 image: nginx:1.27

这个配置表达的是：

优先不要和其他 api-server 放在同一节点。
跨 tenant=prod 的 namespace 一起考虑。
次一级偏好是不要都堆在同一个 zone。
因为都是 preferred，所以资源紧张时不会导致 Pod Pending。

如果业务真的要求“一台节点只能跑一个副本”，再把第一条改成 required。但我一般不会一上来就这么做，除非副本数、节点数、扩容策略都已经算清楚。

排查时先看 Events

如果调度失败，不要先猜，直接 describe：

`1`	`kubectl describe pod api-server-xxx -n default`

重点看最后的 Events，常见会看到类似：

1
2
3


Warning FailedScheduling default-scheduler 0/3 nodes are available:
1 node(s) didn't match Pod's node affinity/selector,
2 node(s) didn't match pod anti-affinity rules.

然后再反查：

1
2
3
4


kubectl get pod -n default -l app=api-server -o wide
kubectl get nodes \
 -L topology.kubernetes.io/zone \
 -L kubernetes.io/hostname

亲和性配置本身不复杂，复杂的是这些规则会跟资源、污点、PVC、拓扑分布一起叠加。我的习惯是先确认硬约束，再看软约束，不要一上来就改 replicas 或重启。

最后还有一个现实建议：不要为了“看起来高可用”把所有规则都写成 required。亲和性配置的目的应该是表达业务边界，不是把调度器绑死。比如核心服务跨节点分散可以硬一点，普通后台任务用 preferred 往往更合适。

参考资料

Kubernetes ConfigMap 过大导致 kubectl apply 失败

Thu, 26 Jun 2025 10:25:34 +0800

整改 Dashboard.json ConfigMap 过大导致 kubectl apply 失败问题

在实际部署 Grafana Dashboard 过程中，因 kubectl apply 会将完整配置写入 kubectl.kubernetes.io/last-applied-configuration 注释，导致 ConfigMap 的 metadata.annotations 长度超限制，出现部署报错。本文围绕「拆分 ConfigMap + 挂载到指定目录」的核心思路，提供 subPath 和 Projected 两种落地方案，同时结合 Kubernetes 官方源码解析限制本质。

一、问题核心回顾

1. 报错现象

执行 kubectl apply 创建 Grafana 相关 ConfigMap（如 grafana-dashboards-general）时，终端提示如下错误，配置创建失败：

`1`	`ConfigMap "grafana-dashboards-general" is invalid: metadata.annotations: Too long: must have at most 262144 characters`

2. 根源分析

kubectl apply** 的注释机制**：kubectl apply 作为 Kubernetes 声明式部署的核心命令，会自动在 ConfigMap 的 metadata.annotations 中添加 kubectl.kubernetes.io/last-applied-configuration 注释 —— 该注释会完整记录上一次 apply 时的配置内容，用于后续对比配置差异、实现增量更新。当 dashboard.json 包含大量可视化配置（如多指标面板、复杂筛选规则）时，注释携带的完整配置会让 metadata.annotations 总长度骤增。
Kubernetes 官方的注释长度限制逻辑：这一限制的底层校验逻辑来自 Kubernetes 源码文件 staging/src/k8s.io/apimachinery/pkg/api/validation/objectmeta.go（具体代码地址：具体代码地址【点击】）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


package validation

func ValidateAnnotationsSize(annotations map[string]string) error {
	var totalSize int64
	for k, v := range annotations {
		totalSize += (int64)(len(k)) + (int64)(len(v))
	}
	if totalSize > (int64)(TotalAnnotationSizeLimitB) {
		return fmt.Errorf("annotations size %d is larger than limit %d", totalSize, TotalAnnotationSizeLimitB)
	}
	return nil
}

从代码可见，Kubernetes 会严格计算所有注释的 “键 + 值” 总字节数，若超过 TotalAnnotationSizeLimitB 定义的 262144 字节（256KB），则直接返回错误，这也是本次 ConfigMap 部署失败的根本原因。

二、整改思路

核心逻辑：将单个超大 ConfigMap 按功能拆分为多个小 ConfigMap，再通过 Kubernetes 卷挂载能力，将所有小 ConfigMap 的配置文件合并挂载到 Grafana 所需的 /home/data/grafana/dashboards 目录。这种方式既规避了单 ConfigMap 注释过长的问题（拆分后单个 ConfigMap 配置 + 注释总长度低于 256KB），又能保证 Grafana 正常加载所有 Dashboard 配置，不影响业务使用。

三、具体实现方案

方案 1：基于 subPath 挂载多 ConfigMap

利用 Kubernetes 的 subPath 特性，可将单个 ConfigMap 中的多个配置文件（或多个 ConfigMap 的配置文件），分别挂载到目标目录的指定文件路径，实现多 ConfigMap 配置的集中存储，且不相互干扰。

1. 前置操作：拆分 ConfigMap

首先将原超大 dashboard.json 按业务功能（如 “系统监控面板”“业务指标面板”“日志分析面板”）拆分为多个独立 JSON 文件，例如拆分为 sys-monitor.json、biz-metric.json、log-analysis.json（归为 grafana-dashboards-group1 ConfigMap）和 user-active.json、data-stat.json、alert-rule.json（归为 grafana-dashboards-group2 ConfigMap）。

执行以下命令创建拆分后的 ConfigMap（需替换文件路径为实际路径）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


# 创建 ConfigMap group1（包含 sys-monitor.json、biz-metric.json、log-analysis.json）

kubectl create configmap grafana-dashboards-group1 \

 --from-file=sys-monitor.json=./sys-monitor.json \

 --from-file=biz-metric.json=./biz-metric.json \

 --from-file=log-analysis.json=./log-analysis.json \

 -n grafana-namespace # 替换为实际 Grafana 所在命名空间

# 创建 ConfigMap group2（包含 user-active.json、data-stat.json、alert-rule.json）

kubectl create configmap grafana-dashboards-group2 \

 --from-file=user-active.json=./user-active.json \

 --from-file=data-stat.json=./data-stat.json \

 --from-file=alert-rule.json=./alert-rule.json \

 -n grafana-namespace

2. Deployment 配置（含 subPath 挂载）

在 Grafana 的 Deployment 配置中，通过 subPath 明确每个配置文件的挂载路径，确保所有拆分后的 JSON 文件最终都集中在 /home/data/grafana/dashboards 目录下，配置示例如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105


apiVersion: apps/v1

kind: Deployment

metadata:

 name: grafana-deployment # Grafana 实际 Deployment 名称

 namespace: grafana-namespace # 替换为实际命名空间

spec:

 replicas: 1

 selector:

 matchLabels:

 app: grafana # Grafana 对应的标签，需与 Pod 标签一致

 template:

 metadata:

 labels:

 app: grafana

 spec:

 containers:

 - name: grafana-container # Grafana 容器名称

 image: grafana/grafana:latest # 实际使用的 Grafana 镜像版本

 command: ["/run.sh"] # Grafana 启动命令（按实际镜像配置调整）

 volumeMounts:

 # 从 group1 挂载 sys-monitor.json 到目标目录

 - name: grafana-dashboards-group1

 mountPath: /home/data/grafana/dashboards/sys-monitor.json # 目标文件路径

 subPath: sys-monitor.json # 对应 ConfigMap 中的文件键名

 # 从 group1 挂载 biz-metric.json

 - name: grafana-dashboards-group1

 mountPath: /home/data/grafana/dashboards/biz-metric.json

 subPath: biz-metric.json

 # 从 group1 挂载 log-analysis.json

 - name: grafana-dashboards-group1

 mountPath: /home/data/grafana/dashboards/log-analysis.json

 subPath: log-analysis.json

 # 从 group2 挂载 user-active.json

 - name: grafana-dashboards-group2

 mountPath: /home/data/grafana/dashboards/user-active.json

 subPath: user-active.json

 # 从 group2 挂载 data-stat.json

 - name: grafana-dashboards-group2

 mountPath: /home/data/grafana/dashboards/data-stat.json

 subPath: data-stat.json

 # 从 group2 挂载 alert-rule.json

 - name: grafana-dashboards-group2

 mountPath: /home/data/grafana/dashboards/alert-rule.json

 subPath: alert-rule.json

 volumes:

 # 定义 group1 卷，关联同名 ConfigMap

 - name: grafana-dashboards-group1

 configMap:

 name: grafana-dashboards-group1

 # 定义 group2 卷，关联同名 ConfigMap

 - name: grafana-dashboards-group2

 configMap:

 name: grafana-dashboards-group2

3. 方案特点

优势：配置逻辑直观，可精确控制每个文件的挂载路径，避免文件覆盖风险，适合配置文件数量固定、变更频率低的场景；
注意：若后续新增或删除 Dashboard 配置文件，需手动在 volumeMounts 中添加或删除对应条目，扩展性较弱。

方案 2：基于 Projected Volume 挂载多 ConfigMap

利用 Kubernetes 的 Projected Volume（投射卷）特性，可将多个 ConfigMap 的所有配置文件自动合并挂载到目标目录，无需手动指定单个文件路径，大幅简化配置，同时支持灵活扩展。

1. 前置操作：拆分 ConfigMap

与方案 1 一致，已将原超大 ConfigMap 拆分为 grafana-dashboards-group1 和 grafana-dashboards-group2 两个小 ConfigMap，确保单个 ConfigMap 配置 + 注释总长度低于 256KB（符合 ValidateAnnotationsSize 函数的限制）。

2. Deployment 配置（含 Projected 挂载）

在 Deployment 中定义 projected 类型卷，关联所有拆分后的 ConfigMap，即可实现所有配置文件自动合并到 /home/data/grafana/dashboards 目录，配置示例如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71


apiVersion: apps/v1

kind: Deployment

metadata:

 name: grafana-deployment # Grafana 实际 Deployment 名称

 namespace: grafana-namespace # 替换为实际命名空间

spec:

 replicas: 1

 selector:

 matchLabels:

 app: grafana # 与 Pod 标签一致

 template:

 metadata:

 labels:

 app: grafana

 spec:

 containers:

 - name: grafana-container # Grafana 容器名称

 image: grafana/grafana:latest # 实际使用的 Grafana 镜像版本

 command: ["/run.sh"] # Grafana 启动命令（按实际调整）

 volumeMounts:

 # 将 Projected 卷挂载到目标目录，所有 ConfigMap 文件自动合并

 - name: grafana-dashboards-proj

 mountPath: /home/data/grafana/dashboards

 readOnly: true # 配置文件仅需读权限，提升安全性

 volumes:

 # 定义 Projected 卷，关联所有拆分后的 ConfigMap

 - name: grafana-dashboards-proj

 projected:

 sources:

 # 引入 group1 ConfigMap，自动包含其所有文件

 - configMap:

 name: grafana-dashboards-group1

 # 引入 group2 ConfigMap，自动包含其所有文件

 - configMap:

 name: grafana-dashboards-group2

 defaultMode: 0644 # 挂载文件默认权限（读权限，符合 Grafana 需求）

3. 方案特点

优势：扩展性强，新增 ConfigMap 时仅需在 projected.sources 中添加对应条目，无需修改 volumeMounts；配置简洁，无需手动指定单个文件路径，减少维护成本；
注意：需确保不同 ConfigMap 中无同名配置文件（否则后加载的 ConfigMap 会覆盖先加载的文件），建议在拆分时统一文件命名规范（如前缀区分功能）。

四、验证与效果

1. 部署验证

执行 kubectl apply -f grafana-deployment.yaml -n grafana-namespace 部署后，通过以下命令验证挂载效果：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


# 1. 查看 Grafana Pod 是否正常启动

kubectl get pods -n grafana-namespace | grep grafana

# 2. 进入 Grafana 容器（替换 <pod-name> 为实际 Pod 名称）

kubectl exec -it <pod-name> -n grafana-namespace -- sh

# 3. 查看目标目录下的文件（应包含所有拆分的 JSON 配置文件）

ls /home/data/grafana/dashboards

# 4. 验证文件内容完整性（以 sys-monitor.json 为例）

cat /home/data/grafana/dashboards/sys-monitor.json

若目标目录下能正常显示所有拆分的配置文件，且文件内容与本地一致，说明挂载成功，同时单个 ConfigMap 未触发 ValidateAnnotationsSize 函数的长度限制。

2. 功能验证

启动 Grafana 服务后，通过浏览器访问 Grafana 界面（按实际部署的访问地址），进入 “Dashboard” 页面：

若能看到所有拆分后的 Dashboard 列表（如 “系统监控”“业务指标” 等）；
点击任一 Dashboard 能正常加载面板、显示指标数据，无配置缺失或报错。

则说明方案生效，ConfigMap 过大问题已解决，且 Grafana 功能正常。

五、总结

两种方案均通过 “拆分 ConfigMap” 的核心思路，规避了 kubectl.kubernetes.io/last-applied-configuration 注释触发 ValidateAnnotationsSize 函数限制的问题，适用于不同场景需求：

subPath 方案：适合配置文件数量固定、需精确控制路径的场景，例如 Dashboard 配置长期稳定、变更极少的情况；
Projected 方案：适合配置文件动态增减、追求简化维护的场景，例如需频繁新增或调整 Dashboard 的情况，也是实际部署中更推荐的方案 —— 兼顾扩展性与配置简洁性，符合 Kubernetes 原生设计理念。

此外，在拆分 ConfigMap 时，建议按 “业务域” 或 “功能模块” 划分，同时规范文件命名（如 sys-xxx.json“biz-xxx.json”），既能严格控制单个 ConfigMap 体量（避免触发 256KB 注释限制），也能提升配置的可维护性，为后续 Dashboard 管理提供便利。

Helm Operator

Mon, 23 Jun 2025 15:11:17 +0800

使用 Kubebuilder 开发 Helm 部署 Operator：从入门到实践

在 Kubernetes 生态中，Operator 模式已成为管理复杂应用生命周期的标准方式。本文将详细介绍如何使用 Kubebuilder 开发一个具有门禁检查功能的 Helm 部署 Operator，帮助你理解控制器调和逻辑、状态管理及事件处理等核心概念。

什么是 Operator？

Operator 是一种包装、部署和管理 Kubernetes 应用的方法，它通过自定义资源 (CR) 和控制器扩展 Kubernetes API，将领域知识编码到软件中，实现应用生命周期的自动化管理。

对于 Helm 应用来说，一个功能完善的 Operator 可以：

自动处理 Helm Chart 的部署、升级和回滚
实现自定义的部署门禁检查（如依赖检查、手动审批）
维护应用状态并提供丰富的可观测性
响应相关资源变化并自动调和状态

开发环境准备

必要工具安装

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# 安装 Kubebuilder

curl -L -o kubebuilder https://github.com/kubernetes-sigs/kubebuilder/releases/download/v3.10.0/kubebuilder\_linux\_amd64

chmod +x kubebuilder && sudo mv kubebuilder /usr/local/bin/

# 安装 kustomize

go install sigs.k8s.io/kustomize/kustomize/v4@latest

# 确保已安装 Go (1.19+) 和 Docker

初始化项目

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# 创建项目目录

mkdir helm-app-operator && cd helm-app-operator

# 初始化项目

kubebuilder init --domain demo.example.com --repo demo.example.com/helm-app-operator

# 创建 API 组和版本

kubebuilder create api --group demo --version v1alpha1 --kind HelmApp

定义自定义资源 (CRD)

编辑 api/v1alpha1/helmapp_types.go 文件，定义我们的 HelmApp 资源：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93


// HelmAppSpec 定义了 Helm 应用的期望状态

type HelmAppSpec struct {

 // Chart 定义 Helm 图表信息

 Chart ChartSpec `json:"chart"`

 // 目标部署命名空间

 TargetNamespace string `json:"targetNamespace"`

 // Helm Values 配置

 Values map[string]interface{} `json:"values,omitempty"`

 // 部署前需要通过的门禁条件

 Gates []GateSpec `json:"gates,omitempty"`

}

// ChartSpec 包含 Helm 图表的元数据

type ChartSpec struct {

 // 图表仓库地址

 Repository string `json:"repository"`

 // 图表名称

 Name string `json:"name"`

 // 图表版本

 Version string `json:"version"`

 // 门禁检查间隔(秒)

 CheckInterval int32 `json:"checkInterval,omitempty"`

}

// GateSpec 定义单个门禁检查项

type GateSpec struct {

 // 门禁名称

 Name string `json:"name"`

 // 门禁类型 (ConfigMapExists/DependencyReady/ManualApproval)

 Type string `json:"type"`

 // 门禁描述

 Description string `json:"description,omitempty"`

 // 是否为强制门禁

 Mandatory bool `json:"mandatory,omitempty"`

}

// HelmAppStatus 定义了 Helm 应用的实际状态

type HelmAppStatus struct {

 // 部署阶段 (Pending/Deploying/Deployed/DeploymentFailed)

 Phase string `json:"phase,omitempty"`

 

 // Helm 发布名称

 ReleaseName string `json:"releaseName,omitempty"`

 

 // 最后部署的版本

 LastDeployedVersion string `json:"lastDeployedVersion,omitempty"`

 

 // 状态条件集合

 Conditions []corev1.PodCondition `json:"conditions,omitempty"`

}

生成 CRD 清单并安装：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# 生成 API 代码

make generate

# 生成 CRD 清单

make manifests

# 安装 CRD 到集群

make install

实现控制器逻辑

控制器是 Operator 的核心，负责协调资源的期望状态与实际状态。我们的控制器需要实现：

门禁检查逻辑
Helm 部署功能
状态管理与更新
事件记录与错误处理

控制器核心结构

编辑 controllers/helmapp_controller.go：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39


// HelmAppReconciler 处理 HelmApp 资源

type HelmAppReconciler struct {

 ctrl.Client

 Scheme *runtime.Scheme

 Log logr.Logger

 Recorder record.EventRecorder

}

// SetupWithManager 设置控制器

func (r *HelmAppReconciler) SetupWithManager(mgr manager.Manager) error {

 return ctrl.NewControllerManagedBy(mgr).

 For(\&demov1alpha1.HelmApp{}).

 Watches(

 \&source.Kind{Type: \&corev1.ConfigMap{}},

 handler.EnqueueRequestsFromMapFunc(r.findHelmAppsForConfigMap),

 ).

 WithOptions(controller.Options{

 MaxConcurrentReconciles: 5,

 }).

 Complete(r)

}

调和逻辑实现

Reconcile 函数是控制器的核心，实现主要的调和逻辑：

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139


// Reconcile 处理 HelmApp 资源的调和逻辑

func (r *HelmAppReconciler) Reconcile(ctx context.Context, req ctrl.Request) (ctrl.Result, error) {

 log := log.FromContext(ctx)

 // 1. 获取 HelmApp 实例

 helmApp := \&demov1alpha1.HelmApp{}

 if err := r.Get(ctx, req.NamespacedName, helmApp); err != nil {

 log.Error(err, "无法获取 HelmApp 资源")

 return ctrl.Result{}, ctrl.IgnoreNotFound(err)

 }

 // 2. 初始化状态

 if helmApp.Status.Phase == "" {

 helmApp.Status.Phase = "Pending"

 if err := r.Status().Update(ctx, helmApp); err != nil {

 log.Error(err, "无法更新 HelmApp 状态")

 return r.handleStatusUpdateError(ctx, helmApp, err)

 }

 r.Recorder.Event(helmApp, corev1.EventTypeNormal, "Initializing", "开始处理 Helm 应用部署")

 return ctrl.Result{Requeue: true}, nil

 }

 // 3. 执行门禁检查

 allGatesPassed, err := r.checkAllGates(ctx, helmApp)

 if err != nil {

 log.Error(err, "门禁检查失败")

 return ctrl.Result{RequeueAfter: 30 * time.Second}, err

 }

 // 4. 如果所有门禁都通过，执行 Helm 部署

 if allGatesPassed && helmApp.Status.Phase != "Deployed" {

 log.Info("所有门禁检查通过，开始部署 Helm 应用")

 helmApp.Status.Phase = "Deploying"

 if err := r.Status().Update(ctx, helmApp); err != nil {

 log.Error(err, "无法更新 HelmApp 状态为部署中")

 return r.handleStatusUpdateError(ctx, helmApp, err)

 }

 // 执行 Helm 部署

 release, err := r.deployWithHelm(ctx, helmApp)

 if err != nil {

 log.Error(err, "Helm 部署失败")

 helmApp.Status.Phase = "DeploymentFailed"

 r.updateCondition(helmApp, "Deployment", corev1.ConditionFalse, "DeploymentError", err.Error())

 r.Recorder.Event(helmApp, corev1.EventTypeWarning, "DeploymentFailed", err.Error())

 if err := r.Status().Update(ctx, helmApp); err != nil {

 return r.handleStatusUpdateError(ctx, helmApp, err)

 }

 return ctrl.Result{RequeueAfter: 60 * time.Second}, nil

 }

 // 更新部署成功状态

 helmApp.Status.Phase = "Deployed"

 helmApp.Status.ReleaseName = release.Name

 helmApp.Status.LastDeployedVersion = release.Chart.Metadata.Version

 r.updateCondition(helmApp, "Ready", corev1.ConditionTrue, "Deployed", "应用部署成功并就绪")

 r.Recorder.Event(helmApp, corev1.EventTypeNormal, "Deployed", fmt.Sprintf("Helm 应用部署成功: %s", release.Name))

 

 if err := r.Status().Update(ctx, helmApp); err != nil {

 log.Error(err, "无法更新 HelmApp 状态为已部署")

 return r.handleStatusUpdateError(ctx, helmApp, err)

 }

 return ctrl.Result{}, nil

 }

 // 5. 如果门禁未通过，定期重试

 if !allGatesPassed {

 log.Info("部分门禁检查未通过，将在稍后重试")

 checkInterval := time.Duration(helmApp.Spec.Chart.CheckInterval) * time.Second

 if checkInterval <= 0 {

 checkInterval = 30 * time.Second

 }

 return ctrl.Result{RequeueAfter: checkInterval}, nil

 }

 // 6. 已部署状态，定期检查

 return ctrl.Result{RequeueAfter: 5 * time.Minute}, nil

}

门禁检查实现

实现三种门禁检查类型：配置检查、依赖检查和手动审批：

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183


// 检查所有门禁条件

func (r *HelmAppReconciler) checkAllGates(ctx context.Context, helmApp *demov1alpha1.HelmApp) (bool, error) {

 log := log.FromContext(ctx)

 allPassed := true

 passedCount := 0

 // 检查每个定义的门禁

 for \_, gate := range helmApp.Spec.Gates {

 gatePassed, reason, message := r.checkGate(ctx, helmApp, gate)

 

 // 更新门禁状态 Condition

 status := corev1.ConditionFalse

 if gatePassed {

 status = corev1.ConditionTrue

 passedCount++

 } else {

 allPassed = false

 if gate.Mandatory {

 log.Info("强制门禁检查未通过", "gate", gate.Name)

 }

 }

 

 r.updateCondition(helmApp, gate.Name, status, reason, message)

 

 // 记录门禁检查事件

 eventType := corev1.EventTypeNormal

 if !gatePassed {

 eventType = corev1.EventTypeWarning

 }

 eventReason := fmt.Sprintf("Gate%s", strings.Title(strings.ToLower(reason)))

 eventMessage := fmt.Sprintf("门禁检查 '%s' %s: %s", gate.Name,

 map[bool]string{true: "通过", false: "未通过"}[gatePassed],

 message)

 r.Recorder.Eventf(helmApp, eventType, eventReason, eventMessage)

 }

 // 更新所有门禁是否通过的汇总 Condition

 allGatesStatus := corev1.ConditionFalse

 if allPassed {

 allGatesStatus = corev1.ConditionTrue

 }

 r.updateCondition(helmApp, "AllGatesPassed", allGatesStatus,

 "GatesCheckComplete", "所有门禁检查已完成")

 return allPassed, nil

}

// 检查单个门禁条件

func (r *HelmAppReconciler) checkGate(ctx context.Context, helmApp *demov1alpha1.HelmApp, gate demov1alpha1.GateSpec) (bool, string, string) {

 switch gate.Type {

 case "ConfigMapExists":

 // 检查指定的 ConfigMap 是否存在

 cm := \&corev1.ConfigMap{}

 if err := r.Get(ctx, types.NamespacedName{

 Name: gate.Name,

 Namespace: helmApp.Spec.TargetNamespace,

 }, cm); err != nil {

 return false, "ConfigMapMissing", fmt.Sprintf("配置文件 %s 不存在", gate.Name)

 }

 return true, "ConfigMapFound", fmt.Sprintf("配置文件 %s 已找到", gate.Name)

 

 case "DependencyReady":

 // 检查依赖的 HelmApp 是否已就绪

 depApp := \&demov1alpha1.HelmApp{}

 if err := r.Get(ctx, types.NamespacedName{

 Name: gate.Name,

 Namespace: helmApp.Namespace,

 }, depApp); err != nil {

 return false, "DependencyMissing", fmt.Sprintf("依赖应用 %s 不存在", gate.Name)

 }

 

 if depApp.Status.Phase != "Deployed" {

 return false, "DependencyNotReady", fmt.Sprintf("依赖应用 %s 尚未就绪", gate.Name)

 }

 return true, "DependencyReady", fmt.Sprintf("依赖应用 %s 已就绪", gate.Name)

 

 case "ManualApproval":

 // 检查手动审批（通过特定 ConfigMap 中的标记）

 approvalCM := \&corev1.ConfigMap{}

 cmName := fmt.Sprintf("approval-%s", helmApp.Name)

 if err := r.Get(ctx, types.NamespacedName{

 Name: cmName,

 Namespace: helmApp.Namespace,

 }, approvalCM); err != nil {

 return false, "ApprovalPending", "等待手动审批"

 }

 

 if approvalCM.Data["approved"] == "true" {

 return true, "Approved", "已获得手动审批"

 }

 return false, "NotApproved", "尚未获得手动审批"

 

 default:

 return false, "UnknownGateType", fmt.Sprintf("未知的门禁类型: %s", gate.Type)

 }

}

状态更新错误处理

状态更新失败时的处理策略非常重要，需要确保状态最终能反映真实情况：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89


// 处理状态更新错误

func (r *HelmAppReconciler) handleStatusUpdateError(ctx context.Context, helmApp *demov1alpha1.HelmApp, originalErr error) (ctrl.Result, error) {

 log := log.FromContext(ctx)

 

 // 记录错误事件

 r.Recorder.Event(helmApp, corev1.EventTypeWarning, "StatusUpdateFailed",

 fmt.Sprintf("状态更新失败: %v", originalErr))

 

 // 检查错误类型

 if apierrors.IsConflict(originalErr) {

 // 资源版本冲突，重新获取资源后重试

 log.Info("状态更新冲突，将重新获取资源后重试")

 if err := r.Get(ctx, types.NamespacedName{Name: helmApp.Name, Namespace: helmApp.Namespace}, helmApp); err != nil {

 log.Error(err, "重新获取资源失败")

 return ctrl.Result{}, err

 }

 return ctrl.Result{Requeue: true}, nil

 }

 

 if apierrors.IsNotFound(originalErr) {

 // 资源已被删除，无需继续处理

 log.Info("资源已被删除，停止状态更新")

 return ctrl.Result{}, nil

 }

 

 // 其他错误，重试几次

 maxRetries := 3

 retryInterval := 2 * time.Second

 var lastErr error

 

 for i := 0; i < maxRetries; i++ {

 time.Sleep(retryInterval)

 if err := r.Status().Update(ctx, helmApp); err != nil {

 lastErr = err

 log.Error(err, "状态更新重试失败", "重试次数", i+1)

 continue

 }

 log.Info("状态更新重试成功")

 return ctrl.Result{}, nil

 }

 

 // 多次重试失败，记录并延迟重试

 log.Error(lastErr, "多次重试后状态更新仍失败")

 return ctrl.Result{RequeueAfter: 10 * time.Second}, lastErr

}

实现 Helm 部署功能

集成 Helm SDK 实现应用部署：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77


// 使用 Helm 部署应用

func (r *HelmAppReconciler) deployWithHelm(ctx context.Context, helmApp *demov1alpha1.HelmApp) (*release.Release, error) {

 settings := cli.New()

 actionConfig := new(action.Configuration)

 

 if err := actionConfig.Init(settings.RESTClientGetter(), helmApp.Spec.TargetNamespace,

 os.Getenv("HELM\_DRIVER"), r.Log.Info); err != nil {

 return nil, fmt.Errorf("无法初始化 Helm 配置: %v", err)

 }

 // 添加 Helm 仓库

 addRepo := action.NewRepoAdd(actionConfig)

 addRepo.URL = helmApp.Spec.Chart.Repository

 addRepo.Update = true

 if \_, err := addRepo.Run(helmApp.Name, helmApp.Spec.Chart.Repository); err != nil {

 return nil, fmt.Errorf("无法添加 Helm 仓库: %v", err)

 }

 // 安装 Helm 图表

 install := action.NewInstall(actionConfig)

 install.ReleaseName = fmt.Sprintf("%s-%s", helmApp.Name, generateRandomString(5))

 install.Namespace = helmApp.Spec.TargetNamespace

 install.CreateNamespace = true

 install.Version = helmApp.Spec.Chart.Version

 // 加载图表

 chartPath, err := install.LocateChart(helmApp.Spec.Chart.Name, settings)

 if err != nil {

 return nil, fmt.Errorf("无法找到 Helm 图表: %v", err)

 }

 // 转换 values 配置

 values, err := structsToValues(helmApp.Spec.Values)

 if err != nil {

 return nil, fmt.Errorf("无法转换 values 配置: %v", err)

 }

 // 执行安装

 release, err := install.Run(chartPath, values)

 if err != nil {

 return nil, fmt.Errorf("Helm 安装失败: %v", err)

 }

 return release, nil

}

构建和部署 Operator

构建镜像

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# 设置镜像仓库（替换为你的仓库）

export IMG=your-registry/helm-app-operator:v0.1.0

# 构建并推送镜像

make docker-build docker-push

# 部署 Operator 到集群

make deploy

创建示例资源

创建 config/samples/demo_v1alpha1_helmapp.yaml：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67


apiVersion: demo.example.com/v1alpha1

kind: HelmApp

metadata:

name: example-webapp

namespace: default

spec:

chart:

 repository: https://charts.bitnami.com/bitnami

 name: nginx

 version: "13.2.25"

 checkInterval: 30 # 门禁检查间隔30秒

targetNamespace: webapps

values:

 replicaCount: 2

 service:

 type: ClusterIP

 port: 80

 resources:

 requests:

 cpu: 100m

 memory: 128Mi

gates:

 - name: required-config

 type: ConfigMapExists

 description: 检查是否存在必要的配置文件

 mandatory: true

 - name: database-service

 type: DependencyReady

 description: 确保数据库服务已部署

 mandatory: true

 - name: production-approval

 type: ManualApproval

 description: 生产环境部署需要手动审批

 mandatory: true

应用示例资源：

`1`	`kubectl apply -f config/samples/demo\_v1alpha1\_helmapp.yaml`

控制器重新入队机制详解

在控制器开发中，理解重新入队机制至关重要，它决定了控制器何时再次处理资源：

返回值	是否重新入队	重试时机	典型场景
`ctrl.Result{}, err`	是	立即	临时错误（如网络波动）
`ctrl.Result{RequeueAfter: t}, nil`	是	延迟 t 时间后	需等待的场景（如门禁未通过）
`ctrl.Result{Requeue: true}, nil`	是	立即	无错误但需重试（如资源未就绪）
`ctrl.Result{}, nil`	否	不重试	状态已达成（如部署完成）

在我们的 Helm Operator 中：

当门禁未通过时，使用 RequeueAfter 按配置的间隔重试：

`1`	`return ctrl.Result{RequeueAfter: checkInterval}, nil`

当部署失败时，延迟 60 秒后重试：

`1`	`return ctrl.Result{RequeueAfter: 60 * time.Second}, nil`

当状态更新失败时，根据错误类型决定重试策略：

`1`	`return r.handleStatusUpdateError(ctx, helmApp, err)`

当所有操作成功完成时，不重新入队：

`1`	`return ctrl.Result{}, nil`

测试与验证

查看资源状态

1
2
3
4
5
6
7


# 查看 HelmApp 资源

kubectl get helmapps -o wide

# 查看详细状态

kubectl describe helmapp example-webapp

模拟门禁通过

创建所需的 ConfigMap：

`1`	`kubectl create configmap required-config -n webapps`

创建依赖的 HelmApp（如果需要）
创建手动审批 ConfigMap：

`1`	`kubectl create configmap approval-example-webapp -n default --from-literal=approved=true`

观察部署过程：

1
2
3


kubectl get pods -n webapps

kubectl get helmapps example-webapp -o jsonpath='{.status.phase}'

总结

本文详细介绍了使用 Kubebuilder 开发 Helm 部署 Operator 的完整流程，包括：

环境搭建和项目初始化
自定义资源 (CRD) 设计与实现
控制器核心逻辑开发，包括：

调和循环实现
门禁检查机制
Helm 部署集成
状态管理与错误处理

部署和测试 Operator

通过这个 Operator，我们可以实现复杂应用的自动化部署流程，包括各种前置检查和审批机制，大大提高了部署的可靠性和可维护性。

Kubebuilder 提供了丰富的工具和框架，使我们能够专注于业务逻辑的实现，而不必关心 Kubernetes API 的细节。掌握 Operator 开发技能，将为你的 Kubernetes 应用管理带来更大的灵活性和自动化能力。

Kubernetes 通过 ServiceAccount 生成 kubeconfig

Tue, 17 Jun 2025 10:19:32 +0800

Kubernetes中通过ServiceAccount自动生成Kubeconfig文件

在Kubernetes集群管理中，我们经常需要为不同的用户或应用创建具有特定权限的访问凭证。本文将介绍如何通过ServiceAccount自动化创建具有只读权限的kubeconfig文件。

背景介绍

在Kubernetes中，ServiceAccount是为Pod中的进程提供身份标识的资源对象。通过RBAC授权机制，我们可以为ServiceAccount分配特定的权限。本文提供的脚本可以自动创建ServiceAccount、分配只读权限，并生成对应的kubeconfig文件。

脚本功能

自动创建ServiceAccount：在指定命名空间中创建服务账号
RBAC权限配置：创建Role和RoleBinding，分配Pod只读权限
Kubeconfig生成：自动获取Token和集群信息，生成完整的kubeconfig文件
Kubernetes版本适配：兼容1.24+版本（需要手动创建Secret）
清理功能：提供完整的资源清理脚本

创建Kubeconfig的脚本

以下脚本将自动创建一个具有Pod只读权限的ServiceAccount，并生成对应的kubeconfig文件。

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106


#!/bin/bash
set -euo pipefail

# 配置变量
NAMESPACE="default" # 指定命名空间（按需修改）
SERVICE_ACCOUNT_NAME="pod-viewer" # 账号名称（修正变量名）
KUBECONFIG_FILE="kubeconfig_${SERVICE_ACCOUNT_NAME}"

echo "=== 开始创建 Pod 只读权限的 ServiceAccount ==="
echo "命名空间: $NAMESPACE"
echo "服务账号: $SERVICE_ACCOUNT_NAME"
echo "Kubeconfig 输出文件: $KUBECONFIG_FILE"
echo ""

# 创建 ServiceAccount
echo "[1/6] 创建 ServiceAccount..."
kubectl -n $NAMESPACE create serviceaccount $SERVICE_ACCOUNT_NAME

# 创建 Role
echo "[2/6] 创建只读 Pod 的 Role..."
kubectl -n $NAMESPACE apply -f - <<EOF
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
 name: pod-reader
rules:
- apiGroups: [""]
 resources: ["pods"]
 verbs: ["get", "list", "watch"]
EOF

# 创建 RoleBinding
echo "[3/6] 创建 RoleBinding..."
kubectl -n $NAMESPACE create rolebinding pod-reader-binding \
 --role=pod-reader \
 --serviceaccount=$NAMESPACE:$SERVICE_ACCOUNT_NAME

# 等待并获取 Secret
echo "[4/6] 处理 ServiceAccount Token..."
SECRET_NAME=""
for i in {1..5}; do
 SECRET_NAME=$(kubectl -n $NAMESPACE get serviceaccount $SERVICE_ACCOUNT_NAME -o jsonpath='{.secrets[0].name}' 2>/dev/null || true)
 [ -n "$SECRET_NAME" ] && break
 echo " - 等待 Secret 创建 ($i/10)..."
 sleep 1
done

if [ -z "$SECRET_NAME" ]; then
 echo " - Kubernetes 1.24+ 检测到无自动创建的 Secret，正在手动创建..."
 SECRET_NAME="${SERVICE_ACCOUNT_NAME}-token"
 kubectl -n $NAMESPACE apply -f - <<EOF
apiVersion: v1
kind: Secret
metadata:
 name: ${SECRET_NAME}
 annotations:
 kubernetes.io/service-account.name: ${SERVICE_ACCOUNT_NAME}
type: kubernetes.io/service-account-token
EOF
 kubectl -n $NAMESPACE patch serviceaccount $SERVICE_ACCOUNT_NAME \
 -p "{\"secrets\":[{\"name\":\"${SECRET_NAME}\"}]}"
fi

# 获取认证信息
echo "[5/6] 获取集群信息..."
SA_TOKEN=$(kubectl -n $NAMESPACE get secret $SECRET_NAME -o jsonpath='{.data.token}' | base64 --decode)
APISERVER=$(kubectl config view --minify -o jsonpath='{.clusters[0].cluster.server}')
CA_CERT=$(kubectl -n $NAMESPACE get secret $SECRET_NAME -o jsonpath='{.data.ca\.crt}')

# 生成 kubeconfig
echo "[6/6] 生成 Kubeconfig 文件..."
cat > $KUBECONFIG_FILE <<EOF
apiVersion: v1
kind: Config
current-context: ${SERVICE_ACCOUNT_NAME}-context
clusters:
- name: default-cluster
 cluster:
 certificate-authority-data: ${CA_CERT}
 server: ${APISERVER}
contexts:
- name: ${SERVICE_ACCOUNT_NAME}-context
 context:
 cluster: default-cluster
 namespace: ${NAMESPACE}
 user: ${SERVICE_ACCOUNT_NAME}
users:
- name: ${SERVICE_ACCOUNT_NAME}
 user:
 token: ${SA_TOKEN}
EOF

echo ""
echo "=== 验证配置 ==="
echo "1. 检查 Context 配置:"
kubectl --kubeconfig=$KUBECONFIG_FILE config get-contexts

echo ""
echo "2. 测试 Pod 访问权限:"
kubectl --kubeconfig=$KUBECONFIG_FILE get pods

echo ""
echo "=== 操作完成 ==="
echo "生成的 Kubeconfig 文件: $KUBECONFIG_FILE"
echo "长期使用建议:"
echo " export KUBECONFIG=\$PWD/$KUBECONFIG_FILE"

二、删除相关配置的脚本文件：

当不再需要这些资源时，可以使用以下脚本进行清理：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55



#!/bin/bash
set -euo pipefail

# 配置变量（必须与创建脚本保持一致）
NAMESPACE="default" # 命名空间
SERVICE_ACCOUNT_NAME="pod-viewer" # 服务账号名称
KUBECONFIG_FILE="kubeconfig_${SERVICE_ACCOUNT_NAME}" # kubeconfig 文件名

echo "=== 开始清理 Pod 只读权限资源 ==="
echo "命名空间: $NAMESPACE"
echo "服务账号: $SERVICE_ACCOUNT_NAME"
echo "Kubeconfig 文件: $KUBECONFIG_FILE"
echo ""

# 删除 RoleBinding
echo "[1/5] 删除 RoleBinding..."
kubectl -n $NAMESPACE delete rolebinding pod-reader-binding --ignore-not-found

# 删除 Role
echo "[2/5] 删除 Role..."
kubectl -n $NAMESPACE delete role pod-reader --ignore-not-found

# 删除 ServiceAccount 及相关 Secret
echo "[3/5] 删除 ServiceAccount 和关联的 Secret..."
kubectl -n $NAMESPACE delete serviceaccount $SERVICE_ACCOUNT_NAME --ignore-not-found
kubectl -n $NAMESPACE delete secret "${SERVICE_ACCOUNT_NAME}-token" --ignore-not-found

# 删除 kubeconfig 文件
echo "[4/5] 删除 Kubeconfig 文件..."
if [ -f "$KUBECONFIG_FILE" ]; then
 rm -v "$KUBECONFIG_FILE"
else
 echo " - 文件不存在: $KUBECONFIG_FILE"
fi

# 验证清理结果
echo "[5/5] 验证资源是否已清理..."
echo " - 检查 ServiceAccount:"
kubectl -n $NAMESPACE get serviceaccount $SERVICE_ACCOUNT_NAME 2>/dev/null || echo " - 已清理"

echo " - 检查 Role:"
kubectl -n $NAMESPACE get role pod-reader 2>/dev/null || echo " - 已清理"

echo " - 检查 RoleBinding:"
kubectl -n $NAMESPACE get rolebinding pod-reader-binding 2>/dev/null || echo " - 已清理"

echo ""
echo "=== 清理完成 ==="
echo "以下资源已被移除："
echo "1. Role: pod-reader"
echo "2. RoleBinding: pod-reader-binding"
echo "3. ServiceAccount: $SERVICE_ACCOUNT_NAME"
echo "4. 关联的 Secret"
echo "5. Kubeconfig 文件: $KUBECONFIG_FILE"

使用方法

创建资源和kubeconfig文件：

`1`	`bash chmod +x create-kubeconfig.sh ./create-kubeconfig.sh`

验证生成的kubeconfig：

1

bash kubectl --kubeconfig=kubeconfig_pod-viewer get pods

清理资源：

`1`	`bash chmod +x cleanup.sh ./cleanup.sh`

Kubernetes Kubelet 与容器运行时交互流程

Wed, 11 Jun 2025 11:28:18 +0800

kubelet cri containerd cni runc 之间的业务交互流程

1. kubelet 与底层交互的过程演变：

2. 1.1版本后的组件角色说明、以及细节抛析

组件	核心作用	子模块/依赖
Kubelet	节点代理，监听 APIServer，管理 Pod 生命周期（创建/销毁/监控）	Volume Manager、CSI 插件、Probe 机制
CRI (gRPC)	Kubernetes 与容器运行时的标准接口，解耦 Kubelet 和具体实现	containerd/CRI-O 的 CRI 插件
Containerd	容器运行时，管理容器镜像、存储和运行（默认通过 runc 实现 OCI 标准）	containerd-shim、runc、CNI
CNI 插件	配置 Pod 网络（IP 分配、网卡、路由规则）	Calico/Flannel/Weave 等具体实现
runc	底层 OCI 运行时，负责创建/启动容器进程（调用 Linux 内核的 Namespace 和 Cgroups）	libcontainer（内核交互层）

Kubernetes on DK Blog

Kubernetes Pod 删除与容器重启时日志到底去哪了？

先给结论

Kubernetes 里的日志是谁在管？

Pod 删除后日志为什么会没？

容器重启时日志会保留吗？

0.log、1.log 到底怎么理解？

还有一种“轮转”：不是重启，而是文件太大

三个典型场景

场景一：Deployment 滚动发布

场景二：CrashLoopBackOff

场景三：节点磁盘被日志打满

为什么“Pod 删除日志就没了”是合理设计？

生产环境应该怎么做？

常用命令整理

最后总结

参考资料

Pod Pending 排查：不是所有 Pending 都是资源不够

第一步：describe Pod

CPU 或内存 request 太大

nodeSelector 或 nodeAffinity 匹配不到节点

节点有 taint，但 Pod 没有 toleration

PVC 没有绑定

anti-affinity 或 topologySpreadConstraints 太硬

一个固定排查顺序

参考资料

Kubernetes HPA 扩缩容不符合预期时怎么查

先看 HPA 当前状态

确认 metrics-server 正常

CPU utilization 依赖 requests

一个完整的 HPA 示例

为什么负载下来了还不缩容

为什么负载上来了也不扩容

参考资料

Pod 为什么没有按预期分散？从 anti-affinity 到 topologySpreadConstraints

先确认实际分布

anti-affinity 能解决什么

topologySpreadConstraints 更像控制倾斜度

怎么选

参考资料

Kubernetes 亲和性与反亲和性配置记录

先看节点标签

nodeSelector 和 nodeAffinity

podAffinity 和 podAntiAffinity

podAntiAffinity 里容易漏掉的配置

matchExpressions：不要只会 matchLabels

namespaces / namespaceSelector：默认只看当前 namespace

matchLabelKeys：跟当前 Pod 的标签值绑定

mismatchLabelKeys：租户隔离时更有用

一个更完整的 Deployment 例子

排查时先看 Events

参考资料

Kubernetes ConfigMap 过大导致 kubectl apply 失败

整改 Dashboard.json ConfigMap 过大导致 kubectl apply 失败问题

一、问题核心回顾

1. 报错现象

2. 根源分析

二、整改思路

三、具体实现方案

方案 1：基于 subPath 挂载多 ConfigMap

1. 前置操作：拆分 ConfigMap

2. Deployment 配置（含 subPath 挂载）

3. 方案特点

方案 2：基于 Projected Volume 挂载多 ConfigMap

1. 前置操作：拆分 ConfigMap

2. Deployment 配置（含 Projected 挂载）

3. 方案特点

四、验证与效果

1. 部署验证

2. 功能验证

五、总结

Helm Operator

使用 Kubebuilder 开发 Helm 部署 Operator：从入门到实践

什么是 Operator？

开发环境准备

必要工具安装

初始化项目

定义自定义资源 (CRD)

实现控制器逻辑

控制器核心结构

`0.log`、`1.log` 到底怎么理解？