Kubernetes API 对象与 Manifest¶

Kubernetes 中的 Namespace、Pod、Deployment、Service 等都是 API 对象。Manifest 是对象的 YAML/JSON 表达，提交给 API Server 后保存为期望状态；控制器再负责让实际状态接近期望状态。

通用结构¶

apiVersion: apps/v1
kind: Deployment
metadata:
  name: order-service
  namespace: order
  labels:
    app.kubernetes.io/name: order-service
    app.kubernetes.io/instance: order-prod
spec:
  replicas: 3
  selector:
    matchLabels:
      app.kubernetes.io/name: order-service
  template:
    metadata:
      labels:
        app.kubernetes.io/name: order-service
    spec:
      containers:
        - name: app
          image: registry.example.com/order-service:1.4.0

字段	作用
`apiVersion`	对象使用的 API 组和版本
`kind`	对象类型
`metadata`	名称、Namespace、Label、Annotation、OwnerReference 等身份信息
`spec`	用户声明的期望状态
`status`	控制器写入的实际状态，不应放进日常部署 YAML

Label、Selector 与 Annotation¶

Label 用于选择和分组对象；Service、Deployment 等通过 Selector 找到目标。Annotation 保存不用于选择的扩展信息，例如工具配置、负责人或外部系统 ID。

kubectl get pods -n order --show-labels
kubectl get pods -n order -l app.kubernetes.io/name=order-service
kubectl label pod <pod> incident=investigating -n order
kubectl annotate deployment/order-service owner=platform-team -n order

Deployment 的 .spec.selector 必须与 Pod Template 的 Label 一致；Service Selector 也必须匹配 Pod Label，否则 Service 没有 EndpointSlice 后端。

期望状态、实际状态和 Condition¶

kubectl get deployment order-service -n order -o yaml
kubectl get deployment order-service -n order \
  -o jsonpath='{.spec.replicas}{" desired / "}{.status.readyReplicas}{" ready\n"}'

generation 表示 spec 变化代数，observedGeneration 表示控制器处理到哪一代。两者不一致时，控制器可能尚未处理最新配置。Condition 则说明 Available、Progressing、Ready 等状态及原因。

声明式操作¶

kubectl diff -f manifests/
kubectl apply --server-side -f manifests/
kubectl get -f manifests/
kubectl delete -f manifests/

生产变更先 diff，再通过 Git/Helm/Argo CD 管理。长期混用 apply、edit、patch 和多个发布工具，容易产生字段所有权冲突和配置漂移。

OwnerReference 与级联删除¶

Deployment 拥有 ReplicaSet，ReplicaSet 拥有 Pod。删除上级对象时，下级对象通常会被垃圾回收。排障时可查看：

kubectl get pod <pod> -n order -o jsonpath='{.metadata.ownerReferences}'
kubectl get rs -n order

不要只修改控制器管理的 Pod；控制器会重新创建并覆盖它。应修改 Deployment/StatefulSet 等上级对象。

Finalizer¶

Finalizer 让对象在删除前完成清理，例如释放云负载均衡或存储。对象长期 Terminating 时检查：

kubectl get <kind> <name> -n <namespace> -o yaml

只有确认清理职责和外部资源状态后才能处理 Finalizer。直接移除可能留下云盘、负载均衡或其他孤儿资源。

API 发现与文档¶

kubectl api-resources
kubectl api-versions
kubectl explain deployment
kubectl explain deployment.spec.strategy
kubectl explain pod.spec.containers.resources

编写 Manifest 前用 kubectl explain 确认目标集群支持的字段和 API 版本，避免照搬旧教程中的已废弃 API。