声明式对象配置

声明式配置的核心是：把资源状态写进文件，然后用 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 描述清楚目的与影响范围，必要时补充回滚方案。

实战补充

把快速入门应用到真实业务时，建议固定一套检查项：资源 requests、就绪探针、日志覆盖、告警阈值、回滚步骤。清单要短小、可重复，并随仓库一起维护，这样每次发布都能快速对齐标准。

排障路径

从现象入手，不要先猜原因。先看事件，再看日志，最后验证流量路径和配置版本是否一致。若访问异常，先确认 readiness 和 endpoints，再逐段排查入口到后端的链路。记录每一步改动，方便回滚和复盘。

小练习

在测试环境做几次常见操作：扩缩容、重启单个 Pod、调整一项配置并验证效果。通过这些小练习，你能更直观地感受到系统收敛速度和异常时的行为。

维护与责任

明确服务归属、值班人和升级窗口，准备常见故障的处理步骤。依赖服务也需要纳入监控和备份计划，确保问题出现时能快速定位和恢复。

交付提醒

发布后用用户视角快速验证一次：访问核心接口、观察延迟和错误率，确认新旧 Pod 的状态稳定。如果涉及存储或网络，顺手核对磁盘用量、DNS 和 endpoints 是否正常。

回滚预案

写下最小可行的回滚步骤，包括需要恢复的配置、镜像版本和校验方式。这样在出现异常时可以迅速还原，而不是现场临时拼步骤。