第 13 篇：后端 Kubernetes 部署模板#

2.1 模板是工程基线，不是万能抽象#

模板的第一职责是提供工程基线。它应该让每个后端服务默认拥有可运行、可观测、可发布、可回滚、可审计的最小能力。比如所有服务都必须有标准 labels，所有 Pod 都必须设置 resources，所有 HTTP API 都必须有 readinessProbe 和 livenessProbe，所有容器默认非 root 运行。

模板不应该试图覆盖所有业务差异。订单服务、搜索服务、报表服务、长连接服务、消费者服务的资源、探针、扩缩容指标和优雅停机时间都可能不同。模板应该把差异变成显式参数，而不是让业务团队复制整份 YAML 后手工改。

模板质量的判断标准不是“字段多不多”，而是“缺省值是否安全、差异是否可审查、故障是否可定位”。一份模板如果让服务能跑但没有资源边界、没有健康检查、没有安全上下文，它只是启动样板，不是生产模板。

2.2 对象组合：Deployment、Service、配置和密钥#

Deployment 是模板核心。它承载镜像、replicas、Pod labels、资源、探针、环境变量引用、安全上下文和发布策略。Service 负责把 Pod 集合变成稳定入口。二者通过 label 和 selector 连接，selector 错误会导致 Service 没有 endpoints，是后端模板最必须统一的地方。

ConfigMap 和 Secret 负责配置分离。普通配置放 ConfigMap，敏感配置放 Secret，再通过 envFrom、显式 env 或 volume mount 注入 Pod。模板要明确：哪些变量是所有服务必备，哪些变量由业务服务声明，哪些敏感值不能出现在普通配置和 Git 明文中。

模板还要处理配置变更的重启语义。修改 ConfigMap 或 Secret 后，已运行 Pod 不一定自动重启。团队需要选择明确策略：通过 Helm/Kustomize 注入 checksum annotation 触发滚动，或者由发布系统在配置变更后重启工作负载。不要让配置变更依赖“手工删 Pod”。

2.3 治理对象：HPA、PDB、ServiceAccount 与 securityContext#

HPA 让服务可以根据指标扩缩容，但它不是容量规划的替代品。没有 requests，HPA 的 CPU 利用率也缺少可靠基准；没有压测，min/max replicas 只是猜测；下游数据库容量不足时，扩容 API 副本可能放大压力。模板可以提供 HPA 结构，但阈值必须结合服务特征设置。

PDB 保护的是自愿驱逐，例如节点维护、集群升级、管理员 drain。它不能防止节点宕机，也不能让单副本服务高可用。模板里给关键服务配置 PDB，可以减少维护期间多个副本同时被驱逐，但前提是服务至少有多个 ready 副本。

ServiceAccount 和 securityContext 是运行时安全基线。默认不要使用 default ServiceAccount 承担过多权限；容器尽量非 root、禁止 privilege escalation、丢弃不需要的 Linux capabilities、根文件系统只读。安全上下文不是装饰字段，它决定容器被攻破后的横向移动和破坏能力。

3.1 从模板参数到 Kubernetes 对象#

模板通常会暴露少量参数：服务名、镜像、tag、replicas、resources、env、secret refs、probe paths、service port、HPA 开关、PDB 开关、安全上下文开关。渲染工具可以是 Helm、Kustomize、Jsonnet、ytt 或内部平台，但核心都是把参数转成 Kubernetes 对象。

渲染阶段最怕“默认值看似方便但不安全”。例如默认不写 resources、默认关闭 probes、默认 root 运行、默认暴露 NodePort，都可能让服务上线时带着隐患。更好的默认是保守安全：必须显式提供资源规格，默认开启探针，默认非 root，默认 ClusterIP，外部入口单独声明。

校验阶段要在 CI 里完成。至少应该做 YAML 语法校验、Kubernetes schema 校验、kubectl --dry-run=server 或等价检查、策略检查。策略可以要求必须有 owner label、必须有 resources、不能使用 latest、不能 privileged、不能缺 readinessProbe。

3.2 控制器如何消费模板对象#

Deployment 控制器消费 Deployment，创建 ReplicaSet 和 Pod；Service 控制器维护 Service 和 EndpointSlice；HPA 控制器读取指标并调整 replicas；PDB 由 eviction API 在自愿驱逐时参考；kubelet 按 Pod spec 启动容器并运行探针。模板渲染完成后，真正工作的是这些控制器。

因此模板排障不能只看渲染结果。Deployment 没有 ready，可能是 Pod Pending、ImagePullBackOff、CrashLoopBackOff 或 readiness 失败；Service 没有 endpoints，可能是 selector 错、Pod labels 错或 Pod not ready；HPA 不扩容，可能是 metrics-server 不可用、requests 缺失或指标没有达到阈值；PDB 不生效，可能是 selector 没匹配到 Pod 或副本数不足。

模板中的对象引用要形成闭环。Deployment labels 要被 Service、HPA、PDB 和监控规则一致使用；Service 端口名称要能被 Ingress、ServiceMonitor 或 Gateway 引用；ConfigMap 和 Secret 名称要和 Deployment env 引用一致。模板的核心难点，正是让这些引用在所有环境中稳定成立。

3.3 伪代码：模板发布流水线#

可以用下面的伪代码理解模板发布流水线。

1
function releaseBackendService(values):
2
    manifests = renderTemplate(values)
3

4
    validateSchema(manifests)
5
    validatePolicy(manifests, rules = [
6
        "no latest image",
7
        "resources required",
8
        "readinessProbe required",
9
        "runAsNonRoot required",
10
        "standard labels required"
11
    ])
12

13
    diff = compareWithCluster(manifests)
14
    requireReview(diff)
15

16
    apply(manifests)
17
    waitForRollout(values.serviceName)
18
    verifyServiceEndpoints(values.serviceName)
19
    verifyMetricsAndLogs(values.serviceName)
20

21
    if verificationFailed:
22
        rollbackOrPauseRollout(values.serviceName)

这段伪代码强调三件事。第一，模板不是发布终点，发布后还要验证 rollout、endpoints、日志和指标。第二，策略检查要前移到 CI，不能等生产事故才发现缺资源或探针。第三，回滚必须建立在版本化模板和可追踪镜像之上，否则只会回滚到另一个不可解释状态。

4.1 ConfigMap、Secret 和 ServiceAccount#

1
apiVersion: v1
2
kind: ConfigMap
3
metadata:
4
  name: order-api-config
5
  labels:
6
    app.kubernetes.io/name: order-api
7
    app.kubernetes.io/component: backend
8
data:
9
  SPRING_PROFILES_ACTIVE: prod
10
  LOG_LEVEL: INFO
11
---
12
apiVersion: v1
13
kind: Secret
14
metadata:
15
  name: order-api-secret
16
type: Opaque
17
stringData:
18
  DB_PASSWORD: change-me
19
---
20
apiVersion: v1
21
kind: ServiceAccount
22
metadata:
23
  name: order-api

ConfigMap 和 Secret 分离普通配置和敏感配置。ServiceAccount 给 Pod 一个明确身份，后续可以绑定最小 RBAC 权限。即使服务暂时不访问 Kubernetes API，也建议不要默认使用权限边界不清的 default ServiceAccount。

4.2 Deployment 和 Service#

1
apiVersion: apps/v1
2
kind: Deployment
3
metadata:
4
  name: order-api
5
  labels:
6
    app.kubernetes.io/name: order-api
7
    app.kubernetes.io/component: backend
8
spec:
9
  replicas: 2
10
  selector:
11
    matchLabels:
12
      app.kubernetes.io/name: order-api
13
  template:
14
    metadata:
15
      labels:
16
        app.kubernetes.io/name: order-api
17
        app.kubernetes.io/component: backend
18
    spec:
19
      serviceAccountName: order-api
20
      securityContext:
21
        runAsNonRoot: true
22
      containers:
23
        - name: api
24
          image: registry.example.com/order-api:1.0.0
25
          ports:
26
            - name: http
27
              containerPort: 8080
28
          envFrom:
29
            - configMapRef:
30
                name: order-api-config
31
            - secretRef:
32
                name: order-api-secret
33
          resources:
34
            requests:
35
              cpu: 200m
36
              memory: 512Mi
37
            limits:
38
              memory: 1Gi
39
          readinessProbe:
40
            httpGet:
41
              path: /actuator/health/readiness
42
              port: http
43
            periodSeconds: 5
44
          livenessProbe:
45
            httpGet:
46
              path: /actuator/health/liveness
47
              port: http
48
            periodSeconds: 10
49
          securityContext:
50
            allowPrivilegeEscalation: false
51
            readOnlyRootFilesystem: true
52
            capabilities:
53
              drop: ["ALL"]
54
---
55
apiVersion: v1
56
kind: Service
57
metadata:
58
  name: order-api
59
spec:
60
  selector:
61
    app.kubernetes.io/name: order-api
62
  ports:
63
    - name: http
64
      port: 80
65
      targetPort: http

Deployment 和 Service 通过统一 label 连接。Service 使用命名端口 http，避免容器端口变化时多个对象都要改数字。安全上下文默认收紧权限，但这要求镜像本身支持非 root 和只读文件系统。

4.3 HPA、PDB 和观察命令#

1
apiVersion: autoscaling/v2
2
kind: HorizontalPodAutoscaler
3
metadata:
4
  name: order-api
5
spec:
6
  scaleTargetRef:
7
    apiVersion: apps/v1
8
    kind: Deployment
9
    name: order-api
10
  minReplicas: 2
11
  maxReplicas: 6
12
  metrics:
13
    - type: Resource
14
      resource:
15
        name: cpu
16
        target:
17
          type: Utilization
18
          averageUtilization: 70
19
---
20
apiVersion: policy/v1
21
kind: PodDisruptionBudget
22
metadata:
23
  name: order-api
24
spec:
25
  minAvailable: 1
26
  selector:
27
    matchLabels:
28
      app.kubernetes.io/name: order-api

部署后先看对象链路：

1
kubectl get deploy,rs,pod,svc,hpa,pdb
2
kubectl rollout status deployment/order-api
3
kubectl get endpointslice -l kubernetes.io/service-name=order-api

HPA 依赖指标系统和资源 requests；PDB 依赖 selector 和 ready Pod 数量。它们写在模板里只是开始，还要通过集群状态验证是否真的工作。

5.1 labels、selector 和命名端口#

labels 是模板治理的基础。推荐使用 Kubernetes 官方推荐的 app.kubernetes.io/name、component、part-of、version 等 label。它们不仅用于 Service selector，还会被监控、日志、告警、成本统计和权限策略复用。label 命名一旦混乱，平台工具就很难统一识别服务。

selector 必须稳定。Deployment 的 selector 和 Pod template labels 要匹配，Service、PDB、NetworkPolicy、ServiceMonitor 等对象也常依赖同一组 label。模板应该把 label 生成逻辑集中管理，避免各环境手工拼接。selector 错误是最典型的“YAML 都存在但系统不工作”。

命名端口能降低对象耦合。容器端口叫 http，Service targetPort、probe port、Ingress backend 都可以引用 http。如果应用从 8080 改到 8081，只要容器端口定义仍叫 http，部分上游对象无需改动。模板中优先使用命名端口，是小细节里的工程质量。

5.2 resources、probes 和运行安全#

resources 是调度和容量治理的入口。requests 太低会造成节点超卖，太高会导致 Pending；limits 太低会 OOMKilled，太高会降低节点保护效果。模板可以给默认档位，例如 small、medium、large，但业务服务要基于压测和线上指标选择，而不是所有服务一刀切。

probes 是发布安全的入口。readiness 决定是否接流量，liveness 决定是否重启，startup 适合慢启动应用。模板应该要求 HTTP API 默认提供 readiness 和 liveness 路径。不要让 liveness 依赖外部数据库短暂状态，否则外部依赖抖动会触发应用集体重启。

securityContext 是运行安全入口。runAsNonRoot、allowPrivilegeEscalation: false、capabilities.drop: ["ALL"] 和只读根文件系统都能降低风险。但模板开启这些约束前，镜像要配合：应用要写入可写目录，证书和临时文件路径要明确，非 root 用户要有必要文件权限。模板和镜像要共同设计。

5.3 HPA、PDB 和 ServiceAccount#

HPA 的前提是指标可用和 requests 合理。CPU 平均利用率是常见起点，但并不适合所有服务。IO 密集型、队列消费者、长连接服务可能更适合自定义指标，例如队列积压、请求延迟或并发数。模板可以提供 HPA 对象，但扩缩容指标需要业务确认。

PDB 要和副本数匹配。minAvailable: 1 对两副本服务能在维护时保留一个 ready Pod；对单副本服务则会阻止自愿驱逐，可能影响节点维护。PDB 不是越严格越好，它是可用性和运维灵活性的平衡。

ServiceAccount 应该默认独立。即使服务暂时不访问 Kubernetes API，独立 ServiceAccount 也方便后续绑定精确权限、审计和策略控制。不要把所有服务都挂在 default ServiceAccount 上，更不要给 default 绑定宽权限。

6.1 新服务接入模板#

新后端服务接入时，应该只需要提供少量必要信息：服务名、镜像仓库、端口、健康接口路径、资源档位、环境变量、是否启用 HPA、是否需要外部入口。模板负责生成标准对象，平台负责校验基线，业务负责确认服务特性。

接入流程最好有自动检查。例如 PR 中如果缺少 resources、readinessProbe、标准 labels 或非 root 安全上下文，CI 直接失败。这样模板不是“建议”，而是可执行的工程约束。约束要少而关键，避免把业务团队压进模板填空游戏。

README 也要与模板一致。开发者应该知道哪些字段可以改，哪些字段不能改，哪些字段由平台注入，哪些字段要走变更审批。模板没有说明文档，就会变成另一种黑盒。

6.2 多环境差异治理#

开发、测试、预发、生产的差异应该体现在参数层，而不是复制四份完全不同 YAML。常见差异包括 replicas、resources、HPA 开关、Ingress 域名、配置值、Secret 引用、日志级别。对象结构尽量一致，差异值显式管理。

测试环境可以资源小、HPA 关闭、PDB 简化；生产环境必须有资源、探针、PDB、安全上下文和观测字段。差异要能通过 code review 看出来，而不是某个人在集群里手工改。下一篇 Helm/Kustomize 会专门讲多环境治理。

配置变更也要进入发布流程。不要让生产问题通过 kubectl edit 临时修改模板对象。临时修复可以救火，但事后必须写回模板参数和版本库，否则下一次发布会覆盖现场修改。

6.3 订单 API 标准化案例#

假设订单 API 需要上线。业务提供镜像 order-api:1.0.0、端口 8080、健康路径 /actuator/health/readiness 和 /actuator/health/liveness、资源档位 medium、最小副本 2、最大副本 6。模板生成 Deployment、Service、HPA、PDB、ConfigMap、Secret 引用和 ServiceAccount。

上线后如果 Service 没有 endpoints，平台首先检查模板生成的 labels 和 selector 是否一致，再检查 Pod readiness。因为所有服务的 label 约定统一，这类问题不会散落在不同命名风格里。排障路径可以标准化。

如果 HPA 不扩容，团队检查 metrics-server、自定义指标、requests 和 HPA events。因为 HPA 结构来自统一模板，排障重点就集中在指标和阈值，而不是每个服务的 YAML 写法都不同。

7.1 Service 没有 endpoints#

先看 Service selector 和 Pod labels。

1
kubectl get svc order-api -o yaml
2
kubectl get pod -l app.kubernetes.io/name=order-api --show-labels
3
kubectl get endpointslice -l kubernetes.io/service-name=order-api

如果 selector 匹配不到 Pod，说明模板 label 生成或服务名参数有问题。如果 selector 匹配到 Pod 但 endpoints 为空，继续看 Pod readiness。readiness 失败时，Service 默认不会把 Pod 当成可用后端。

这类问题最适合通过模板统一避免。label 和 selector 不应该由业务服务手写多份，而应该由模板集中生成。业务只提供服务名，模板负责保证对象间引用一致。

7.2 HPA、PDB 和权限问题#

HPA 不工作时，先看 HPA 状态和事件。

1
kubectl describe hpa order-api
2
kubectl top pod -l app.kubernetes.io/name=order-api

如果显示无法获取指标，检查 metrics-server 或自定义指标链路；如果 CPU 利用率 unknown，检查容器是否设置 requests；如果达到阈值但不扩容，看 maxReplicas、稳定窗口和集群资源。HPA 不是单独一个 YAML，它依赖指标系统和资源声明。

PDB 不生效或阻塞节点维护时，看 selector 和当前可用 Pod。

1
kubectl describe pdb order-api
2
kubectl get pod -l app.kubernetes.io/name=order-api

单副本服务配严格 PDB，可能导致自愿驱逐无法进行。关键服务应该提升副本数，而不是用 PDB 假装高可用。

权限问题通常表现为容器启动失败、文件无法写入或 API 访问被拒绝。看 Pod events、容器日志、securityContext、ServiceAccount 和 RBAC。不要为了快速修复就关闭所有安全约束，应该修镜像权限、挂载可写目录或补最小权限。

7.3 模板渲染和发布证据链#

模板渲染失败时，先看渲染结果。

1
helm template ./chart -f values-prod.yaml
2
kubectl apply --dry-run=server -f rendered.yaml

如果使用 Kustomize：

1
kubectl kustomize overlays/prod
2
kubectl apply --dry-run=server -k overlays/prod

发布失败时，沿对象链路看。

1
kubectl rollout status deployment/order-api
2
kubectl describe deployment order-api
3
kubectl get rs,pod,svc,hpa,pdb -l app.kubernetes.io/name=order-api
4
kubectl logs -l app.kubernetes.io/name=order-api --tail=200

排障结论应该写回模板或参数。模板问题修模板，业务参数问题修 values，镜像问题修构建产物，配置问题修 ConfigMap/Secret 来源。不要在集群里手工 patch 后就结束。

8.1 模板基线和业务差异边界#

模板基线应该强制统一：labels、resources、probes、安全上下文、ServiceAccount、Service 端口命名、基础 annotations。这些是平台排障和治理依赖的公共语言，不应该每个服务自由发挥。

业务差异应该参数化：副本数、资源档位、探针路径、HPA 指标、PDB 策略、配置项、是否暴露入口。这些差异和业务负载有关，不能由模板写死。模板设计要明确哪些字段可改、哪些字段不可改。

如果某个服务确实需要突破基线，例如需要写根文件系统、需要特殊 capability、需要长 terminationGracePeriod，应当通过例外机制审批并记录原因。例外可以存在，但不能变成默认绕过。

8.2 安全、容量和成本边界#

安全上，模板只能提供默认约束，不能替代镜像安全、依赖扫描、Secret 轮换、RBAC 审计和网络策略。容器非 root 运行也不代表应用没有漏洞。模板是安全体系的一层。

容量上，模板默认资源档位只是起点。真实服务要根据压测和线上指标调整。HPA 可以应对波动，但如果数据库是瓶颈，扩容 API 会放大数据库压力。容量治理必须跨服务看调用链。

成本上，模板统一后很容易“一键加副本、一键开 HPA”。这会让资源消耗快速增长。生产模板应该配合成本标签、命名空间配额、告警和容量评审，避免所有服务都用过大的默认规格。

8.3 版本、评审和审计边界#

模板本身要版本化。平台升级模板时，要知道哪些服务会受到影响，如何灰度，如何回滚。业务服务引用模板版本，不应该每次平台改模板都无感影响所有生产服务。

模板变更要 code review。新增字段、修改默认值、改变安全上下文、调整 HPA 策略，都可能影响大量服务。模板是平台基础设施，不是普通配置片段。

审计要能回答：某个服务当前使用哪个模板版本，哪些参数覆盖了默认值，谁批准了生产差异，最近一次变更改了什么。没有这些记录，模板规模化后反而会增加黑盒感。

9.1 适合使用标准模板的场景#

无状态 HTTP API、内部 RPC 服务、普通后台消费者，最适合使用标准模板。它们通常需要 Deployment、Service、ConfigMap/Secret、resources、probes、HPA、PDB 和安全上下文，差异也比较容易参数化。

多团队共享平台时，标准模板尤其重要。统一 labels、资源、探针和安全基线，可以让平台监控、日志、告警、成本、审计和排障形成统一语言。否则每个团队一套 YAML，平台治理成本会迅速上升。

新服务接入也适合模板化。模板能帮助新人避开常见坑：忘写 resources、忘写 readiness、selector 不匹配、Secret 明文提交、root 运行、ServiceAccount 权限不清。

9.2 不适合直接套模板的场景#

有状态数据库、消息队列核心节点、存储系统，不适合直接套无状态后端模板。它们可能需要 StatefulSet、PVC、备份恢复、稳定身份和专门运维流程。

一次性 Job、CronJob、DaemonSet、GPU 任务、长连接网关，也不适合直接套普通 API 模板。它们的生命周期、资源、探针和发布方式不同，需要专门模板或平台能力。

强合规或高权限服务也不能只套默认模板。它们可能需要额外审计、网络隔离、专用 ServiceAccount、Pod Security、准入控制和安全评估。默认模板是下限，不是上限。

9.3 默认建议#

默认建议是：所有无状态后端 API 使用统一模板；模板强制标准 labels、resources、readiness/liveness、安全上下文和 ServiceAccount；业务只通过参数表达镜像、资源档位、配置、探针路径、副本和扩缩容策略。

排障默认顺序是：先看模板渲染结果，再看对象是否应用成功，然后看 Deployment rollout、Pod events、Service endpoints、HPA/PDB 状态，最后结合业务日志和指标。不要只看某一个 YAML 字段就下结论。

演进默认路径是：先有手写标准模板，再抽象成 Helm 或 Kustomize，再加入 CI 策略检查，再建立模板版本和例外审批。模板治理是逐步生长的，不是一次写出万能平台。