声明式对象配置

声明式配置的核心是：把资源状态写进文件，然后用 kubectl apply 统一管理。它让变更可审计、可复现，也更适合团队协作。

本节在基础流程上补充 diff/预览、标签规范、Kustomize 与 GitOps 实践等内容。

为什么推荐声明式

变更可追踪（适合 git 管理）。
易回滚（用历史版本重放）。
结果一致（重复 apply 不会破坏状态）。

多对象示例

apiVersion: v1
kind: Namespace
metadata:
  name: demo
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: api
  namespace: demo
spec:
  replicas: 2
  selector:
    matchLabels:
      app: api
  template:
    metadata:
      labels:
        app: api
    spec:
      containers:
        - name: api
          image: nginx:1.25

常用流程

kubectl apply -f app.yaml
kubectl diff -f app.yaml
kubectl delete -f app.yaml

应用顺序

建议先创建 Namespace，再应用 RBAC，然后再部署业务资源，避免依赖缺失。

标签与选择器

统一 labels，方便 Service 与监控系统发现：

metadata:
  labels:
    app: api
    tier: backend

Server-Side Apply

Server-side apply 可以明确字段归属，降低冲突风险：

kubectl apply --server-side -f app.yaml

若发生冲突，检查 fieldManager，避免多套系统同时改同一字段。

字段归属与冲突

Server-side apply 会记录字段归属。多套系统同时改同一字段会产生冲突。建议明确 field manager，并让每个系统只管理自己的字段。

kubectl apply --server-side --field-manager=dev-cli -f app.yaml

Diff 与预览

上线前用 diff 查看差异：

kubectl diff -f app.yaml || true

Patch 与 Apply

apply 用于完整期望状态。
patch 用于小范围修改：

kubectl patch deploy api -p '{"spec":{"replicas":3}}'

生产环境建议通过 Git 变更，再 apply。

Apply 与 Prune

需要删除清单中已移除的资源时，可使用 prune：

kubectl apply -f ./manifests -l app=api --prune

这样集群状态会更贴近仓库。

Dry-run

不真正写入资源的校验方式：

kubectl apply -f app.yaml --dry-run=server

Kustomize 基础

Kustomize 内置于 kubectl，便于环境差异管理：

kubectl apply -k overlays/prod

用于管理镜像版本、环境变量和配置差异。

Kustomize 示例

一个最小示例：

# kustomization.yaml
resources:
  - ../../base
images:
  - name: nginx
    newTag: "1.26"

应用方式：

kubectl apply -k overlays/prod

不可变字段

selectors 等字段不可修改，变更时必须重建资源。设计阶段要谨慎。

命名与目录结构

建议按应用或环境组织目录，例如：

base/ 共享资源。
overlays/dev, overlays/prod 环境差异。

这样复用性更高，变更也更清晰。

漂移与收敛

手动修改会导致漂移，重新 kubectl apply 会将资源拉回期望状态，这也是 GitOps 的基础。

配置拆分

RBAC、配置与业务清单分文件管理，减少误改风险，也便于 review。

实用建议

在 CI 中使用 kubectl diff。
清单尽量小而明确。
通过 git tag 标记可回滚版本。

变更审阅清单

标签与选择器是否一致？
requests/limits 是否设置？
Secret 是否与配置分离？
回滚路径是否清晰？

常见问题

冲突：多套工具同时管理同一字段。
缺少 Namespace：应用顺序错误。
不可变字段：selector 或 service 类型不可修改。

预览与校验

建议在 CI 里执行 kubectl diff 或 kubectl apply --dry-run=server，提前发现错误。

排查流程

kubectl get -f app.yaml
kubectl describe -f app.yaml
kubectl diff -f app.yaml

版本推进流程

变更合并到主分支后再由 CI 或 GitOps 控制器发布，确保上线内容与审阅一致。

实操要点

先做快速盘点：kubectl get nodes、kubectl get pods -A、kubectl get events -A。
对比“期望状态”和“实际状态”，kubectl describe 往往能解释漂移或失败原因。
名称、Label、Selector 要一致，避免 Service 或控制器找不到 Pod。
关键清单变更要走评审流程。

快速检查清单

资源定义与业务意图一致。
Namespace、权限、镜像与环境匹配。
上线前具备健康探针与可观测日志。
变更通过版本控制审阅。

安全与合规

避免把 Secret 提交到仓库或聊天记录。敏感配置应放到受控路径，必要时启用审计与加密。

规范化建议

保持 YAML 格式一致，减少 diff 噪音；清单尽量模块化，便于不同团队分工维护。

建议在 CI 中启用基础校验与格式检查，降低上线风险。

变更记录

每次变更用 PR 描述清楚目的与影响范围，必要时补充回滚方案。

收个尾：声明式的价值是“好回滚”

声明式这套玩法最实用的地方，不是看起来更“工程化”，而是出事时你能快速回到一个确定的状态。

所以尽量别在生产集群里手改 YAML。当你真的需要改时：

先在 PR 里看 diff
合并后从同一份清单 apply
出问题就回到上一个 commit/tag，再 apply 回去

你把这条链路走顺了，很多线上问题反而会更简单。