📚 课程目录第2章声明式模型基础

2. 声明式模型基础：声明式 vs 命令式配置、Kubernetes声明式API、YAML/JSON资源定义

2.1 声明式 vs 命令式：两种配置哲学

在云原生与 GitOps 实践中，声明式（Declarative）与命令式（Imperative）是两种根本不同的配置管理范式。理解二者的差异是掌握声明式发布模型的前提。

维度	命令式（Imperative）	声明式（Declarative）
核心思想	描述“如何做”（How）——执行一系列步骤	描述“要什么”（What）——定义最终状态
操作方式	逐条执行指令（如 `kubectl run`、`kubectl scale`）	提交完整资源清单（如 `kubectl apply -f deployment.yaml`）
幂等性	非幂等——重复执行可能产生不同结果	幂等——相同清单产生相同最终状态
可审计性	弱——操作历史分散在终端日志中	强——资源清单本身就是版本化审计记录
GitOps 适配	不适用——无法通过 Git 驱动	天然适配——Git 仓库作为单一事实来源
典型工具	`kubectl create`、`kubectl expose`、Shell 脚本	`kubectl apply`、Helm、Kustomize、Argo CD

  关键认知：GitOps 要求所有环境变更必须通过声明式配置驱动。命令式操作（如临时 kubectl exec 调试）仅允许在非生产环境且事后必须同步回声明式清单。

2.2 Kubernetes 声明式 API 设计原理

Kubernetes 的声明式 API 是其核心设计哲学。它通过 Reconciliation Loop（调谐循环） 机制，持续将集群实际状态拉向用户声明的期望状态。

2.3 YAML/JSON 资源定义：声明式配置的载体

Kubernetes 使用 YAML（首选）或 JSON 格式来描述资源对象。每个资源定义包含四个核心字段组：

apiVersion：API 版本（如 apps/v1、v1）
kind：资源类型（如 Deployment、Service、ConfigMap）
metadata：元数据（name、namespace、labels、annotations）
spec：期望状态描述（资源的具体配置）

最佳实践：始终使用 YAML 而非 JSON 编写资源定义。YAML 支持注释、多行字符串、锚点引用，可读性远超 JSON。仅在 API 调用或工具内部使用 JSON。

2.3.1 典型 Deployment 声明式定义示例

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
  namespace: production
  labels:
    app: nginx
    tier: frontend
spec:
  replicas: 3
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.25-alpine
        ports:
        - containerPort: 80
        resources:
          requests:
            cpu: 100m
            memory: 128Mi
          limits:
            cpu: 500m
            memory: 256Mi

2.4 声明式配置的 GitOps 工作流

在 GitOps 模式下，声明式配置清单存储在 Git 仓库中，通过自动化工具（如 Argo CD、Flux）同步到目标集群。下图展示了从代码提交到集群生效的完整链路：

2.5 声明式配置的幂等性与收敛性

声明式模型的两个关键数学性质决定了 GitOps 的可靠性：

性质	定义	GitOps 意义
幂等性	同一份清单多次 apply，最终状态不变	重试安全、回滚可预测、集群漂移可自动修复
收敛性	无论初始状态如何，系统最终收敛到期望状态	集群故障后自动恢复、手动修改被自动覆盖

⚠️ 常见陷阱：声明式配置并非万能。以下场景需要额外处理：
• 有状态应用：StatefulSet 的存储卷声明（PVC）删除需谨慎
• 动态生成字段：如 Service 的 clusterIP，需使用 kubectl apply --server-side
• Operator 管理的资源：需确保 Operator 本身也遵循声明式模式

2.6 声明式配置的版本化与审计

Git 仓库天然为声明式配置提供版本控制、变更审计和协作能力。每个资源文件的变更历史都可通过 Git 日志追溯：

# 查看特定资源文件的变更历史
git log --oneline --follow deploy/nginx/deployment.yaml

# 比较两个版本的差异
git diff v1.0.0 v1.1.0 -- deploy/nginx/

# 回滚到上一个版本
git revert HEAD --no-edit
git push origin main

  实践要点：每个环境（dev/staging/prod）应有独立的目录或分支。资源文件按 namespace/资源类型/资源名称.yaml 组织，确保可发现性。避免在同一个 YAML 文件中定义多个不相关的资源。