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

2. K8s声明式管理基础：YAML/JSON声明式配置、kubectl apply原理、声明式 vs 命令式

2.1 声明式配置的核心：YAML与JSON

Kubernetes 声明式管理的基石是资源清单（Manifest），通常以 YAML 或 JSON 格式编写。YAML 因其可读性高、支持注释，成为社区首选。每个清单文件描述了一个或多个 Kubernetes 对象的期望状态（Desired State）。

  关键原则： 你告诉 K8s “最终要什么”，而不是“每一步怎么做”。系统内部的控制器会持续协调（Reconcile），确保实际状态与期望状态一致。

2.1.1 最小化 YAML 结构示例

apiVersion: v1                # API 版本，决定资源 schema
kind: Pod                     # 资源类型
metadata:
  name: nginx-pod             # 资源名称（命名空间内唯一）
  labels:
    app: nginx                # 标签，用于选择与关联
spec:
  containers:
  - name: nginx
    image: nginx:1.25
    ports:
    - containerPort: 80

2.1.2 声明式配置的四大字段

字段层级	作用	说明
`apiVersion`	API 版本标识	决定资源 schema 与控制器版本，如 `apps/v1`、`networking.k8s.io/v1`
`kind`	资源类型	Pod、Deployment、Service、Namespace、NetworkPolicy 等
`metadata`	元数据	name、namespace、labels、annotations
`spec`	期望规格	资源的具体配置，如容器镜像、端口、副本数、网络规则

最佳实践： 始终将清单文件纳入 Git 仓库进行版本控制。这是“GitOps”和“基础设施即代码（IaC）”的基础，也是后续多租户隔离与制品签名链路追溯的前提。

2.2 kubectl apply 原理：声明式协调引擎

kubectl apply 是声明式管理的核心命令。它并非简单的“创建或更新”，而是执行一次服务端协调（Server-Side Apply）或客户端协调（Client-Side Apply）。从 K8s 1.22 起，服务端协调成为默认行为。

2.2.1 工作流程（服务端协调）

发送清单： 用户将完整 YAML/JSON 发送至 API Server。
字段级所有权标记： API Server 解析清单，为每个字段标记“管理者”（通过 managedFields 字段记录）。
合并与冲突检测： 如果多个管理者修改同一字段，系统会报冲突，拒绝覆盖，防止配置被意外覆盖。
存储期望状态： 将最终合并后的完整对象存入 etcd。
控制器协调： 对应的控制器（如 Deployment Controller）检测到期望状态变化，开始执行实际变更（如滚动更新 Pod）。

避坑提示： 不要混用 kubectl apply 和 kubectl create/delete 管理同一资源。命令式操作会破坏 managedFields 的追踪，导致后续 apply 出现意外冲突或资源漂移。

2.2.2 声明式协调流程（SVG图）

2.3 声明式 vs 命令式：范式对比

理解两种范式的差异，是构建安全、可审计的多租户平台的前提。命令式关注“如何做”，声明式关注“最终状态”。

维度	声明式（Declarative）	命令式（Imperative）
操作方式	`kubectl apply -f manifest.yaml`	`kubectl run`、`kubectl create deployment`、`kubectl expose`
状态管理	期望状态持久化在 etcd，控制器自动协调	直接执行命令，不保留完整期望状态
可重复性	高，清单文件可版本控制、可复现	低，依赖操作顺序和上下文
审计与追溯	强，Git 历史 + managedFields 可追踪变更来源	弱，仅依赖操作日志，难以关联到具体配置
多租户隔离	天然适合，通过 Namespace + RBAC + NetworkPolicy 声明式定义租户边界	容易产生配置漂移，租户边界难以固化
制品签名集成	可在 CI 中对清单文件签名，验证后再 apply	难以在命令执行时嵌入签名验证

2.3.1 为什么多租户隔离必须选择声明式？

边界固化： 租户的 Namespace、ResourceQuota、NetworkPolicy 通过清单文件定义，不可被运行时命令随意修改。
变更审批： 所有变更通过 Git Merge Request 触发，天然具备审批与审计能力。
回滚能力： 声明式配置支持 kubectl apply --server-side --force-conflicts 或直接回退到历史版本。
签名链路： 在 CI 中对 YAML 清单进行 Cosign 签名，在 CD 中验证签名后再 apply，确保配置未被篡改。

  课程关联： 后续章节将基于声明式配置，构建“多租户隔离 → 制品签名 → 发布证据链”的完整安全链路。本章的 YAML 结构与 apply 原理是整门课程的技术地基。

2.4 声明式 vs 命令式：适用场景对比（SVG图）

实战建议： 在开发环境中，可以使用命令式快速验证；但在任何需要隔离、审计、签名的场景中，必须使用声明式管理。本课程后续所有实践均基于声明式 YAML 清单。