📚 课程目录第3章声明式管理基础

3. 声明式管理基础：YAML 语法回顾、Kubernetes 声明式 API 哲学、kubectl apply 与声明式配置

声明式管理是 Kubernetes 的核心操作范式，也是实现 Resource Quota 与证书轮换等自动化运维的基础。本章从 YAML 语法、声明式 API 哲学、kubectl apply 实践三个层面，建立声明式配置的完整认知。

3.1 YAML 语法核心回顾

YAML（YAML Ain't Markup Language）是 Kubernetes 资源清单的标准序列化格式。以下要点是编写合法清单的基础：

语法要素	规则说明	常见错误
缩进	使用空格，禁止 Tab；同一层级缩进量一致	混用 Tab 与空格导致解析失败
键值对	`key: value`，冒号后必须跟一个空格	遗漏冒号后空格，值被当作字符串拼接
字符串	无引号、单引号、双引号均可；含特殊字符时建议加引号	未对 `:`、`#` 等字符加引号导致歧义
列表	以 `-` 开头，元素与父级缩进对齐	列表项缩进不一致，被解析为嵌套对象
注释	`#` 开头，仅支持单行注释	注释内包含未转义的引号或冒号
多行字符串	`\|` 保留换行，`>` 折叠换行为空格	混淆 `\|` 与 `>` 导致日志格式异常

  实践要点： 在编写 Resource Quota 或 Certificate 资源时，优先使用 kubectl explain 查看字段结构，避免手动拼写 YAML 导致的缩进或类型错误。

3.2 Kubernetes 声明式 API 哲学

声明式 API 的核心思想是：用户描述期望状态（Desired State），系统持续调和（Reconcile）至实际状态（Actual State）。这与命令式操作形成鲜明对比。

声明式 vs 命令式： 命令式关注“如何做”（如 kubectl run），声明式关注“做成什么样”（如 kubectl apply -f quota.yaml）。在证书轮换场景中，声明式配置可确保每次轮换后状态与清单一致，避免人工操作遗漏。

声明式 API 的三大支柱：

资源对象（Resource Object）： 每个 Kubernetes 资源（Pod、Quota、Certificate）都是一个 JSON/YAML 对象，包含 apiVersion、kind、metadata、spec、status 五个核心字段。
控制器模式（Controller Pattern）： 控制器通过 Informer 监听资源变化，将实际状态向期望状态收敛。例如，ResourceQuota 控制器确保 Namespace 内资源用量不超过配额。
最终一致性（Eventual Consistency）： 系统不保证即时生效，但保证在有限时间内达到期望状态。证书轮换时，cert-manager 控制器会异步签发新证书并更新 Secret。

3.3 kubectl apply 与声明式配置

kubectl apply 是声明式管理的核心命令。它通过对比本地清单与集群中已有资源的差异，生成补丁（Patch）并应用到 API Server，实现幂等更新。

3.3.1 命令格式与常用参数

# 创建或更新单个资源
kubectl apply -f resource-quota.yaml

# 创建或更新目录下所有 YAML 文件
kubectl apply -f ./manifests/

# 从标准输入读取清单
cat quota.yaml | kubectl apply -f -

# 查看 apply 后的资源状态
kubectl apply -f quota.yaml --dry-run=client   # 仅验证，不提交
kubectl apply -f quota.yaml --server-side      # 服务端 apply（K8s v1.22+）

3.3.2 声明式配置工作流

编写清单： 在本地 YAML 文件中定义资源的期望状态。
验证清单： 使用 kubectl apply --dry-run=client 或 kubectl validate 检查语法与 schema。
应用清单： 执行 kubectl apply -f 将清单提交至集群。
状态确认： 使用 kubectl get、kubectl describe 查看资源状态。
持续调和： 控制器自动将实际状态向清单定义的期望状态收敛。

注意： 不要混用 kubectl apply 与 kubectl create/kubectl replace。混用会导致资源注解（last-applied-configuration）不一致，引发意外的字段覆盖或删除。

3.3.3 声明式配置与 Resource Quota 示例

以下是一个完整的 ResourceQuota 声明式清单，展示如何通过 YAML 定义配额期望状态：

apiVersion: v1
kind: ResourceQuota
metadata:
  name: compute-quota
  namespace: production
spec:
  hard:
    requests.cpu: "4"
    requests.memory: "8Gi"
    limits.cpu: "8"
    limits.memory: "16Gi"
    persistentvolumeclaims: "5"
    pods: "20"

应用该清单后，Kubernetes 会持续监控 production 命名空间的资源用量，确保不超过上述硬限制。当证书轮换需要创建临时 Pod 时，该配额会阻止超出限制的调度。

3.4 声明式配置最佳实践

清单版本管理： 所有 YAML 清单纳入 Git 仓库，通过 GitOps 工具（如 ArgoCD、Flux）自动同步。
避免手动编辑： 不要使用 kubectl edit 或 kubectl patch 直接修改集群资源，始终通过更新本地清单后重新 apply。
使用命名规范： 清单文件名与资源名称、命名空间对应，便于审计与故障排查。
启用服务端 Apply： Kubernetes v1.22+ 推荐使用 --server-side 参数，由 API Server 管理字段所有权，避免客户端冲突。
结合 Dry Run： 在 CI 流水线中先执行 --dry-run=server 验证权限与 schema，再执行实际 apply。

证书轮换场景提示： 使用声明式方式管理 Certificate 资源（cert-manager CRD）时，每次轮换只需更新 YAML 中的 spec.duration 或 spec.renewBefore 字段，然后执行 kubectl apply -f certificate.yaml。控制器会自动处理证书签发、Secret 更新与轮换逻辑，无需手动干预。