声明式配置是 Kubernetes 真正能在团队里规模化运作的关键之一。它不是简单地“用 YAML”，而是把期望状态写下来、让变更可审阅、让回滚有抓手、让集群能持续被拉回到一个可解释的状态。

什么叫声明式

声明式并不只是“我写了个配置文件”。它更强调：

  • 目标状态被明确写下来
  • 这份状态是可审阅的
  • 变更是可重复执行的
  • 集群能被重新收敛回这份状态

所以 kubectl 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 diff -f app.yaml
kubectl apply -f app.yaml
kubectl get -f app.yaml

这个顺序很重要：先看差异，再应用，再观察结果。

为什么这套方式更安全

  • 变更可以进 git 审阅
  • 重复 apply 通常是安全的
  • 回滚可以直接回到旧 commit / tag
  • 漂移更容易被识别和纠正

从团队协作角度看，它最大的价值不是“看起来规范”，而是别人也能知道你本来想让系统变成什么样。

几个很值钱的声明式习惯

  • namespace 尽量写明确
  • labels 尽量从一开始统一
  • 按职责拆分清单
  • apply 前先看 kubectl diff
  • 发布前写好回滚路径

这些习惯很朴素，但能减少很多线上误操作。

apply 和 patch 怎么分

当你要表达完整期望状态时，用 apply。

当你只是做一个非常局部、临时的调整时，用 patch。

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

但在生产环境里，更健康的做法通常还是把期望状态放进文件，而不是靠大量 patch 维持集群。

漂移为什么这么危险

手改线上资源最麻烦的地方，不只是“可能改错”，而是它会制造第二份事实来源。

一旦 manifest 和线上真实状态不一致，大家就会开始搞不清楚：

  • 应该信 git 里的 YAML
  • 还是信集群里当前状态

这也是为什么这篇和下面几篇天然连着看：

  • kubernetes-quickstart-introduction.md
  • kubernetes-quickstart-architecture.md
  • kubernetes-quickstart-deployment-replicaset.md

前面那些文章讲的是控制器如何持续对账，这篇则告诉你“系统到底在对哪份账”。

除了 apply 之外，最值得会的几条命令

apply 前看差异

kubectl diff -f app.yaml

服务端 dry-run

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

整个目录一起 apply

kubectl apply -f ./manifests

用 Kustomize overlay

kubectl apply -k overlays/prod

顺序真的比很多人想的更重要

一个比较稳的顺序通常是：

  1. Namespace
  2. RBAC 和策略
  3. Config / Secret
  4. Workload
  5. Service / Ingress

顺序一乱，很多错误会显得比实际复杂得多。

apply 之前最好看什么

  • labels 和 selectors 是否还对得上
  • namespace 是否正确
  • 是否误改了不可变字段
  • requests 是否齐全
  • Secret 是否被安全处理
  • 回滚目标是否明确

FAQ

Q: 只有做 GitOps 时，声明式配置才有意义吗？ A: 不是。GitOps 只是声明式运维的一种强化形式。即使没有控制器，受审阅的 manifest + 可重复 apply 也已经比手工命令稳很多。

Q: 为什么配置漂移这么麻烦？ A: 因为一旦 manifest 和线上状态不一致，回滚、排障和交接都会变慢，而且谁都不敢确定哪份才是真正的源头。

Q: 什么时候该开始关心 server-side apply？ A: 当多套工具或多个团队开始同时管理同一批资源，并且字段归属冲突越来越明显时。

下一步阅读

  • 接着读 kubernetes-quickstart-deployment-replicaset.md，理解发布和 rollout 行为
  • 再读 kubernetes-quickstart-configmap-secret.md，看声明式配置如何落到应用配置上
  • 如果你要进入更稳妥的发布方式，继续读 kubernetes-quickstart-canary-release.md

收个尾

声明式配置最值钱的地方，是让变更变得更可解释、更可审查、更可恢复。这样集群就不再是“某个人敲过一些命令的地方”，而是一个可以被团队共同理解和恢复的系统状态。

参考链接