16.1.5 API设计与声明式管理

原理与架构草图#

Kubernetes API 以资源为中心，所有对象通过 REST 接口暴露，核心字段包含 apiVersion、kind、metadata、spec、status，控制平面通过 watch + reconcile 让实际状态收敛到期望状态。

文章图片

安装与准备（kubectl 示例）#

以 Linux 为例安装 kubectl，并验证 API Server 可访问。

# 安装 kubectl（示例：下载稳定版）
curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
chmod +x kubectl
sudo mv kubectl /usr/local/bin/

# 验证版本
kubectl version --client

# 查看当前集群上下文与 API 是否可达
kubectl config current-context
kubectl cluster-info

命令解释：
- kubectl version --client：只查看客户端版本，确认安装成功。
- kubectl cluster-info：访问 API Server，验证连通性与权限。

声明式管理示例（Deployment + Service）#

创建一个完整示例，体现 apiVersion/kind/metadata/spec/status 模型与幂等更新。

文件路径： manifests/nginx-deploy-svc.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web-nginx
  namespace: default
  labels:
    app: web
spec:
  replicas: 2
  selector:
    matchLabels:
      app: web
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxUnavailable: 1
      maxSurge: 1
  template:
    metadata:
      labels:
        app: web
    spec:
      containers:
      - name: nginx
        image: nginx:1.25
        ports:
        - containerPort: 80
        env:
        - name: ENV
          value: "prod"
---
apiVersion: v1
kind: Service
metadata:
  name: web-svc
  namespace: default
spec:
  selector:
    app: web
  ports:
  - port: 80
    targetPort: 80
  type: ClusterIP

# 应用清单（声明式、幂等）
kubectl apply -f manifests/nginx-deploy-svc.yaml

# 查看资源状态
kubectl get deploy,rs,pod,svc -l app=web -o wide

# 查看期望状态与实际状态差异
kubectl diff -f manifests/nginx-deploy-svc.yaml

命令解释：
- kubectl apply：以声明式方式提交期望状态。
- kubectl diff：对比集群实际状态与本地清单，避免漂移。

资源关系示例（ConfigMap 注入）#

展示上层对象与资源注入关系。

文件路径： manifests/configmap-demo.yaml

apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config
data:
  APP_MODE: "blue"
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: app-with-cm
spec:
  replicas: 1
  selector:
    matchLabels:
      app: cm-demo
  template:
    metadata:
      labels:
        app: cm-demo
    spec:
      containers:
      - name: demo
        image: busybox:1.36
        command: ["sh", "-c", "echo $APP_MODE; sleep 3600"]
        env:
        - name: APP_MODE
          valueFrom:
            configMapKeyRef:
              name: app-config
              key: APP_MODE

kubectl apply -f manifests/configmap-demo.yaml
kubectl logs deploy/app-with-cm

预期效果： 日志输出 blue，说明 ConfigMap 通过环境变量注入 Pod。

API 分组与版本化示例#

查看某资源的 API 版本与可用资源。

# 查看某资源使用的 API 版本
kubectl get deployment web-nginx -o yaml | head -n 5

# 查看集群支持的 API 资源
kubectl api-resources | head -n 10

命令解释：
- kubectl api-resources：列出 API Server 支持的所有资源与所属组/版本。

访问控制（RBAC）示例#

创建一个只读 Pod 的角色并绑定给用户。

文件路径： manifests/rbac-read-pod.yaml

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: pod-reader
  namespace: default
rules:
- apiGroups: [""]
  resources: ["pods"]
  verbs: ["get", "list", "watch"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: pod-reader-binding
  namespace: default
subjects:
- kind: User
  name: dev-user
roleRef:
  kind: Role
  name: pod-reader
  apiGroup: rbac.authorization.k8s.io

kubectl apply -f manifests/rbac-read-pod.yaml

变更与回滚示例（不可变字段提示）#

Service 的 clusterIP 不可变，需重建。

# 查看 Service 关键字段
kubectl get svc web-svc -o yaml | grep -n "clusterIP"

# 错误示例：尝试修改不可变字段（会报错）
kubectl patch svc web-svc -p '{"spec":{"clusterIP":"10.96.0.10"}}'

预期错误： field is immutable
处理方式：

kubectl delete svc web-svc
kubectl apply -f manifests/nginx-deploy-svc.yaml

排错清单（API 与声明式问题）#

# 1. 资源未生效：查看事件与控制器调谐
kubectl describe deploy web-nginx

# 2. API 访问失败：检查当前上下文与凭据
kubectl config view --minify

# 3. 资源漂移：对比差异
kubectl diff -f manifests/nginx-deploy-svc.yaml

# 4. RBAC 权限不足：模拟请求
kubectl auth can-i list pods --as=dev-user -n default

常见原因：
- 清单 selector 不匹配导致 Service 无端点；
- 角色未绑定或命名空间不一致；
- 修改不可变字段导致 apply 失败。

练习#

  1. 创建一个 Deployment，将 replicas 从 2 改为 3，使用 kubectl diff 观察差异并应用。
  2. 为 default 命名空间创建只读 ConfigMap 的 RBAC 角色并验证权限。
  3. 使用 kubectl get --watch 观察 Pod 的状态变化，记录从 Pending 到 Running 的过程。
  4. 尝试将 Service 类型改为 NodePort，验证变更流程与访问方式。