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

2. 声明式资源模型基础

2.1 声明式 vs 命令式：两种运维哲学

在基础设施与应用发布领域，操作方式可分为两大范式：命令式（Imperative） 和 声明式（Declarative）。理解二者的区别是掌握 GitOps 的前提。

维度	命令式（Imperative）	声明式（Declarative）
核心思想	“如何做”——描述操作步骤	“做什么”——描述最终状态
操作对象	直接操作 API 或 CLI 执行动作	提交资源清单，由系统自动调和
幂等性	非幂等，重复执行可能产生不同结果	幂等，重复提交相同清单结果一致
可审计性	依赖操作日志，难以追溯	资源清单即真相来源（Source of Truth）
典型示例	`kubectl run nginx --image=nginx`	`kubectl apply -f deployment.yaml`
适用场景	调试、临时操作、快速验证	生产环境、CI/CD、多集群管理

  关键认知： GitOps 的核心前提是“声明式”。只有当你用声明式描述系统期望状态时，Git 才能成为不可变的真相来源，自动化调和循环才能成立。

2.2 Kubernetes 资源模型（KRM）

Kubernetes 资源模型（KRM）是声明式管理的具体实现。所有资源都遵循统一的结构：API 版本（apiVersion）、资源类型（kind）、元数据（metadata）、规格（spec） 和 状态（status）。

apiVersion：定义资源所属的 API 组和版本，如 apps/v1、v1。
kind：资源类型，如 Deployment、Service、ConfigMap。
metadata：标识信息，包括 name、namespace、labels、annotations。
spec：用户声明的期望状态（Desired State）。
status：系统回写的当前实际状态（Actual State），由 Controller 持续更新。

实践要点： 在 GitOps 工作流中，Git 仓库只存储 apiVersion、kind、metadata 和 spec。status 由集群内部维护，不应提交到 Git。

2.3 YAML/JSON 声明式语法

Kubernetes 资源清单通常使用 YAML 或 JSON 编写。YAML 因其可读性成为首选，JSON 常用于 API 传输。以下是一个完整的 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
        ports:
        - containerPort: 80
        resources:
          requests:
            memory: "256Mi"
            cpu: "250m"
          limits:
            memory: "512Mi"
            cpu: "500m"

常见陷阱： YAML 对缩进敏感，禁止使用 Tab 键，必须使用空格。字段名区分大小写，replicas 与 Replicas 是不同的字段。建议在提交前使用 kubectl dry-run 或 yamllint 验证语法。

2.4 资源状态期望值（Desired State）

声明式模型的核心是 期望值（Desired State）。它不是单一数值，而是资源规格中所有字段的集合。系统通过调和循环持续将实际状态向期望状态收敛。

资源类型	期望值关键字段	调和目标
Deployment	`spec.replicas`、`spec.template.spec.containers[].image`	运行指定数量的 Pod，使用指定镜像版本
Service	`spec.selector`、`spec.ports[].port`	将流量路由到匹配标签的 Pod
ConfigMap	`data` 键值对	将配置数据注入 Pod 环境变量或文件
PersistentVolumeClaim	`spec.resources.requests.storage`、`spec.accessModes`	绑定满足容量和访问模式的 PersistentVolume
HorizontalPodAutoscaler	`spec.minReplicas`、`spec.maxReplicas`、`spec.targetCPUUtilizationPercentage`	根据负载自动调整副本数

2.5 声明式管理的核心优势

可复现性：相同的 YAML 清单在任何集群上产生相同的结果。
版本控制：所有变更通过 Git 提交记录，支持回滚、分支、Code Review。
自动化调和：系统持续自愈，无需人工干预。
团队协作：多人并行修改不同资源，通过 PR 流程合并。
多环境一致性：开发、测试、生产环境使用同一套清单，仅参数化差异。

GitOps 最佳实践： 始终使用 kubectl apply 而非 kubectl create 或 kubectl run。将 apply 操作封装在 CI/CD 流水线中，确保 Git 仓库始终是唯一的操作入口。