K8s Deployment 名过长致 Pod 名截断与日志目录代际标识丢失排查

记录时间：2026-07-29
环境：K8s 生产集群 swj-kj-prod（kjds 租户）/ ArgoCD GitOps / Helm chart gzeport-jar 1.2.13 / 共享 NFS 日志 PVC jar-log-data-pvc

一、问题现象

kjds 租户下 bordertradeplatform 模块的日志共享 PVC 上，同一模块不同服务的日志目录命名格式不一致：

# export-service（正常三段）：deployment名 - RS哈希(10位) - Pod随机(5位)
gzeport-bordertradeplatform-export-service-6994c56fff-jv5np

# messageprocess-export-service（异常两段）：deployment名 - Pod随机(5位)，少了 RS 哈希段
gzeport-bordertradeplatform-messageprocess-export-service-p7j8s

messageprocess-export-service 与 messageprocess-import-service 的 Pod 名只剩 deployment 名 + 5 位随机后缀，丢失了中间的 ReplicaSet 哈希段。由于 RS 哈希是区分发布版本（代际）的唯一标识，丢失后导致：该服务 12 副本却堆了 23 个日志目录，新旧版本混在一起无法按代际识别，给日志定位和清理带来困难。

二、排查过程

2.1 怀疑 Chart 版本不同导致 workload 类型差异

这两个服务的 Helm chart 版本不同：

最初怀疑 1.2.13 把 workload 从 Deployment 改成了 ReplicaSet 或其它控制器（不同控制器的 Pod 命名规则不同）。

尝试 1（推翻）：读取 1.2.13 的 templates/deployment.yaml，kind: Deployment 没变，仍是标准 Deployment。而且 messageprocess-import-service 用的是 1.2.12，目录命名同样异常——同 chart 版本出现两种结果，证明与 chart 版本无关。

2.2 从命名长度切入，定位截断

Deployment 管控的 Pod 命名链为：

{Deployment名}-{ReplicaSet的pod-template-hash(10位)}-{随机5位}

而 Pod 名有 63 字符硬上限（RFC 1123 DNS label）。把两个服务的名字量一下：

echo -n "gzeport-bordertradeplatform-messageprocess-export-service" | wc -c   # 57
echo -n "gzeport-bordertradeplatform-export-service" | wc -c                 # 42

messageprocess 的标准 Pod 名会到 74 字符，超出 63 上限。K8s 的处理是：取 ReplicaSet 名的前 58 字符，再拼 5 位随机后缀。截断点正好落在 Deployment 名后的连字符处，RS 哈希的 10 位被整个砍掉，Pod 名退化成 {Deployment名}-{随机5位}，长度恰好 63。

实测用户给出的目录名长度验证：

echo -n "gzeport-bordertradeplatform-messageprocess-export-service-p7j8s" | wc -c   # 63，正好卡在上限
echo -n "gzeport-bordertradeplatform-export-service-7574dfc98b-dbrpj" | wc -c       # 59

数字对得上。根因就是 Deployment 名过长触发 K8s 的 Pod 名 63 字符截断，跟 chart 版本无关。

2.3 顺带确认功能不受影响

截断只影响 Pod 名字，不影响 RS 通过 label selector 管控 Pod：

• Pod 运行、服务发现、Ingress 都不受影响（走 Service 名和 label）
• pod-template-hash 标签的值本身没有被截断（标签值上限也是 63，但哈希只有 10 位），监控和查询仍能按哈希区分代际
• 受影响的只是 PVC 日志目录的可读性（目录名取自截断后的 Pod 名）

三、根因分析

1. messageprocess-import/export-service 的 fullnameOverride 为 gzeport-bordertradeplatform-messageprocess-export-service（57 字符），名字要和 Maven <module> 对齐，无法缩短。
2. 标准 Deployment Pod 名（名-RS哈希-随机）达 74 字符，超 K8s 63 字符上限，被截断。
3. 截断把 RS 哈希段砍掉，Pod 名只剩 名-随机。
4. 该服务 /AppHome/logs 用 subPathExpr: '{{ .Release.Name }}/$(POD_NAME)' 挂载共享 PVC，目录名直接取 $(POD_NAME)，因此日志目录也丢失了 RS 哈希段，无法按代际区分。

社区的经验阈值是 Deployment 名 ≤ 47 字符（63 – 1 – 10 – 1 – 5 = 46），超过就可能触发截断。

四、解决方案

不动 Deployment 名（保持与 Maven 模块对齐），改 subPathExpr 让日志目录按发布版本分层。做法是单独暴露 RS 自动注入的 pod-template-hash 标签，用它做目录的中间层。

改动 1：暴露 RS 哈希标签为环境变量

在 env 段新增（注意 fieldRef 的 label 取值语法）：

- name: POD_HASH
  valueFrom:
    fieldRef:
      fieldPath: metadata.labels['pod-template-hash']

改动 2：subPathExpr 加入哈希分层

# 改动前
subPathExpr: '{{ .Release.Name }}/$(POD_NAME)'
# 改动后
subPathExpr: '{{ .Release.Name }}/{{ .Release.Name }}-$(POD_HASH)/$(POD_NAME)'

渲染后目录结构（三层）：

{Release.Name}/                              # 第1层：release 名（ArgoCD releaseName，等于 serverName）
└── {Release.Name}-{hash}/                   # 第2层：release 名 + RS 哈希
    └── {POD_NAME}/                          # 第3层：截断后的 Pod 名

注意：这里用的是 {{ .Release.Name }}，在本环境 ArgoCD 的 releaseName 取自 serverName（即 messageprocess-export-service），不带 gzeport-bordertradeplatform- 前缀，因此第2层目录名是 messageprocess-export-service-{hash}，并非完整的 RS 名 gzeport-bordertradeplatform-messageprocess-export-service-{hash}。二者前缀不同但哈希一致，代际区分功能不受影响。若要目录名与真实 RS 完全一致，第2层前缀应改用 {{ include "gzeport.fullname" . }}（取 fullnameOverride）。

五、验证

5.1 本地 helm 渲染（已通过）

OCI registry 是内网，本地拉不到 chart，但 chart 源码在本地，直接用路径渲染：

helm template messageprocess-export-service /path/to/gzeport-jar-chart/ \
  -n kjds \
  -f application/kjds/bordertradeplatform/messageprocess-export-service/values.yaml \
  | grep subPathExpr

输出确认 POD_HASH 环境变量和三层 subPathExpr 渲染正确。

5.2 集群验证

hash 标签可读（已确认）：集群上用 downward API 实测，pod-template-hash 标签能正常取到，POD_HASH 方案功能成立：

kubectl -n kjds get pod -l app=gzeport-bordertradeplatform-messageprocess-export-service \
  -o jsonpath='{range .items[*]}{.metadata.name}{"  hash="}{.metadata.labels.pod-template-hash}{"\n"}{end}'

待验证：配置尚未 push。push 后 ArgoCD 会自动同步（kjds 租户 automated.prune + selfHeal），届时查看 PVC 是否出现三层目录结构 {Release.Name}/{Release.Name}-{hash}/{POD_NAME}。

六、注意事项

• 名字不能改短：fullnameOverride 要和 Maven <module> 名对齐，强行缩短会破坏服务名、Ingress path、镜像 repo 等下游引用，得不偿失。
• 截断不影响功能：RS 用 label selector 管 Pod，不靠名字前缀匹配；服务发现和 Ingress 走 Service 名。唯一受影响的是日志目录可读性。
• 旧目录残留：现存的无哈希分层的旧日志目录不会自动迁移，需手动清理或等既定的 60 天压缩 / 180 天删除策略处理。
• 第三层 Pod 名仍很长：$(POD_NAME) 仍是截断后的 63 字符名，无法绕过（Pod 名由 K8s 决定）；有了第2层哈希分层后不影响代际识别。
• 47 字符经验阈值：新服务命名时尽量把 Deployment 名控制在 47 字符以内，可彻底规避此问题。

七、参考资料

• Why you should keep Deployment names to 47 characters or less — Medium
• Kubernetes Issue #116447 — Deployment name too long, ReplicaSet creation
• Kubernetes 官方文档 — 对象名称与 ID（63 字符限制）
• Kubernetes 文档 — Downward API（环境变量方式暴露标签）