Kubernetes 核心资源字段讲解与实战案例

面向：Kubernetes 入门、日常运维、交付部署与故障排查。整理日期：2026-10-27。

本文讲常用稳定 API 和高频字段，不罗列全部 API。示例为学习案例，镜像标签仅为示范，不代表生产版本推荐；实际使用应替换为可访问、经过验证的镜像，生产建议固定摘要。未连接集群，未执行部署与业务验证。版本支持最终以目标集群的 kubectl explain 和服务端校验为准。

目录

1. 先看资源全景与关系
2. YAML 公共字段与字段查询
3. Namespace：命名空间
4. Pod：容器运行的基本单位
5. Deployment 与 ReplicaSet
6. StatefulSet：稳定身份与持久存储
7. DaemonSet：节点级常驻任务
8. Job 与 CronJob
9. HPA：水平自动扩缩容
10. PV、PVC 与 StorageClass
11. Service、DNS 与 EndpointSlice
12. Ingress 与 Gateway API
13. ConfigMap 与 Secret
14. 必须补充的运行与治理知识
15. 贯通实验与验收
16. 故障定位速查
17. 学习顺序与官方资料

1. 先看资源全景与关系

Kubernetes 的核心工作方式：你声明期望状态，控制器持续尝试让实际状态接近期望状态。创建资源成功，只表示 API 接受了配置，不代表应用已经可用。

Namespace
 ├─ Deployment → ReplicaSet → Pod
 ├─ StatefulSet → Pod → PVC → PV → 实际存储
 ├─ DaemonSet → 各符合条件节点上的 Pod
 ├─ CronJob → Job → Pod
 ├─ HPA → 调整 Deployment / StatefulSet 等目标的副本数
 ├─ Service → EndpointSlice → 后端 Pod 地址
 ├─ Ingress → Service → Pod
 └─ ConfigMap / Secret / ServiceAccount → 被 Pod 引用

箭头不全部表示所有权：例如 Service 按标签选择 Pod，并不创建或拥有 Pod；PVC 与 PV 是绑定关系。Pod 模板的入口统一记为 spec.template，但 CronJob 要多经过一层 spec.jobTemplate.spec.template。

2. YAML 公共字段与字段查询

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
  namespace: k8s-notes
  labels:
    app: web
  annotations:
    description: "学习示例"
spec:
  replicas: 2
  # 具体字段依 kind 而定；此片段不是完整 Deployment

ConfigMap、Secret 主要配置在顶层 data 等字段，并不是每种资源都使用 spec。

# 先确认当前集群与命名空间
kubectl config current-context
kubectl version
kubectl api-resources
kubectl api-resources --namespaced=false
kubectl api-versions

# 直接向目标集群查询字段，比背诵全部 YAML 更实用
kubectl explain deployment --api-version=apps/v1
kubectl explain deployment.spec.strategy --api-version=apps/v1
kubectl explain pod.spec.containers.resources
kubectl explain statefulset.spec.volumeClaimTemplates
kubectl explain cronjob.spec.timeZone --api-version=batch/v1
kubectl explain hpa.spec --api-version=autoscaling/v2

# 读取实际状态；包含 Secret 的输出不要随意分享
kubectl get deployment web -n k8s-notes -o yaml
kubectl describe deployment web -n k8s-notes

YAML 使用空格缩进。containers、ports 等是列表，前面有 -；环境变量值和类似 "80" 的字符串建议加引号。command 类似覆盖镜像 ENTRYPOINT，args 类似覆盖 CMD；不会自动运行 shell，只有显式使用 sh -c 才处理管道、变量等 shell 语法。

参考：Kubernetes API。

3. Namespace：命名空间

apiVersion: v1
kind: Namespace
metadata:
  name: k8s-notes
  labels:
    environment: learning

资源名例如 web 可以同时存在于不同 Namespace。Namespace 本身不会自动阻止网络互通，也不会自动施加 CPU、内存配额；应结合 RBAC、NetworkPolicy、ResourceQuota。

kubectl get ns
kubectl get pods -n k8s-notes
kubectl get pods -A
# 修改当前上下文的默认命名空间，会影响之后不带 -n 的命令
kubectl config set-context --current --namespace=k8s-notes

常见系统命名空间包括 default、kube-system、kube-public、kube-node-lease。不要在不清楚用途时修改系统资源。删除命名空间会连带删除其中资源，不能作为普通排错手段。

参考：Namespaces。

4. Pod：容器运行的基本单位

同一 Pod 内容器共享网络，可通过 localhost 通信；通过显式挂载同一个 volume 共享文件。Pod 重建通常产生新 UID、新 IP；容器重启和 Pod 重建是不同事件。

4.1 常用字段路径

4.2 可独立学习的 Pod 示例

apiVersion: v1
kind: Pod
metadata:
  name: toolbox
  namespace: k8s-notes
  labels:
    app: toolbox
spec:
  restartPolicy: Always
  terminationGracePeriodSeconds: 20
  automountServiceAccountToken: false
  initContainers:
    - name: init-file
      image: busybox:1.36
      command: ["sh", "-c", "echo initialized > /work/status.txt"]
      volumeMounts:
        - name: work
          mountPath: /work
  containers:
    - name: toolbox
      image: busybox:1.36
      command: ["sh", "-c", "cat /work/status.txt; sleep 3600"]
      env:
        - name: APP_MODE
          value: "learning"
      resources:
        requests:
          cpu: 50m
          memory: 32Mi
        limits:
          cpu: 200m
          memory: 64Mi
      volumeMounts:
        - name: work
          mountPath: /work
  volumes:
    - name: work
      emptyDir: {}

emptyDir 能跨同一个 Pod 内的容器重启保留数据，但 Pod 被删除或移离节点后不能依赖其数据保留。长期服务通常用控制器管理，而不是直接创建裸 Pod。

4.3 requests、limits 与 QoS

1000m CPU = 1 CPU；512Mi 是内存单位，别把内存误写为 512m。调度看 requests 和节点可分配资源，不是只看 kubectl top 当前是否空闲。

常见按容器声明资源的配置下：所有容器 CPU/内存 request 与 limit 均齐全且相等，可得到 Guaranteed；全部不声明一般是 BestEffort；其余通常为 Burstable。QoS 影响资源压力下的行为，但不是“Guaranteed 永不被驱逐”的承诺。新版本的 Pod 级资源等能力需单独查目标版本。

参考：资源管理。

4.4 三种探针

有 startupProbe 时，startup 成功前不会执行 readiness/liveness 探测。readiness 失败本身不触发容器重启。不要把数据库暂时不可达直接设为所有实例的 liveness 失败条件，容易造成集体重启。

参考：探针配置。

5. Deployment 与 ReplicaSet

Deployment 用于管理可替换的副本，如 Web、API。ReplicaSet 负责副本数量，Deployment 在其上管理版本更新；日常修改 Deployment，避免手工修改它管理的 ReplicaSet 或 Pod。

5.1 核心字段

5.2 完整案例：带资源限制和探针的 Web

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
  namespace: k8s-notes
spec:
  replicas: 2
  revisionHistoryLimit: 3
  minReadySeconds: 5
  progressDeadlineSeconds: 600
  selector:
    matchLabels:
      app: web
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 1
      maxUnavailable: 0
  template:
    metadata:
      labels:
        app: web
    spec:
      automountServiceAccountToken: false
      terminationGracePeriodSeconds: 30
      containers:
        - name: nginx
          image: nginx:1.28
          ports:
            - name: http
              containerPort: 80
          resources:
            requests:
              cpu: 100m
              memory: 64Mi
            limits:
              cpu: 500m
              memory: 128Mi
          startupProbe:
            httpGet:
              path: /
              port: http
            periodSeconds: 2
            failureThreshold: 30
          readinessProbe:
            httpGet:
              path: /
              port: http
            periodSeconds: 5
            timeoutSeconds: 2
            failureThreshold: 3
          livenessProbe:
            httpGet:
              path: /
              port: http
            periodSeconds: 10
            timeoutSeconds: 2
            failureThreshold: 3

这里更新时可临时多 1 个 Pod，目标是保持 2 个可用副本，但需要额外资源、镜像拉取与新实例健康。正在退出的 Pod 可能让观察到的总数短时更高。

maxSurge 百分比向上取整，maxUnavailable 百分比向下取整；两者不能同时为 0。仅改 Deployment 自身的 metadata.labels 不会触发 Pod 模板更新。

kubectl get deploy,rs,pods -n k8s-notes -l app=web
kubectl rollout status deployment/web -n k8s-notes --timeout=120s
kubectl rollout history deployment/web -n k8s-notes
# 以下为实际变更命令，仅在自己的实验资源上执行
kubectl rollout restart deployment/web -n k8s-notes
kubectl rollout undo deployment/web -n k8s-notes

回滚主要恢复 Pod 模板版本，不会自动恢复外部数据库、ConfigMap 内容和存储数据。参考：Deployments。

6. StatefulSet：稳定身份与持久存储

适合需要稳定身份、固定卷关联的应用。StatefulSet 不自动完成数据库主从复制、选主或备份；“3 个数据库 Pod”不等于“数据库高可用”。

案例：两个独立持久化站点

前提：已存在可动态供给的 StorageClass lab-storage，请替换为实际名称。这不是数据库集群案例。

apiVersion: v1
kind: Service
metadata:
  name: site-headless
  namespace: k8s-notes
spec:
  clusterIP: None
  selector:
    app: site
  ports:
    - name: http
      port: 80
      targetPort: http
---
apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: site
  namespace: k8s-notes
spec:
  serviceName: site-headless
  replicas: 2
  podManagementPolicy: OrderedReady
  selector:
    matchLabels:
      app: site
  updateStrategy:
    type: RollingUpdate
  template:
    metadata:
      labels:
        app: site
    spec:
      automountServiceAccountToken: false
      initContainers:
        - name: prepare-index
          image: busybox:1.36
          command:
            - sh
            - -c
            - 'test -f /data/index.html || echo "created by $HOSTNAME" > /data/index.html'
          volumeMounts:
            - name: data
              mountPath: /data
      containers:
        - name: nginx
          image: nginx:1.28
          ports:
            - name: http
              containerPort: 80
          readinessProbe:
            httpGet:
              path: /
              port: http
          resources:
            requests:
              cpu: 100m
              memory: 64Mi
            limits:
              cpu: 500m
              memory: 128Mi
          volumeMounts:
            - name: data
              mountPath: /usr/share/nginx/html
  volumeClaimTemplates:
    - metadata:
        name: data
      spec:
        accessModes: [ReadWriteOnce]
        storageClassName: lab-storage
        resources:
          requests:
            storage: 1Gi

预期名称：Pod 为 site-0、site-1；PVC 为 data-site-0、data-site-1。默认集群域 cluster.local 时，单个 Pod DNS 类似 site-0.site-headless.k8s-notes.svc.cluster.local。DNS 发布受就绪状态等影响。

默认通常保留 PVC，缩容或删除 StatefulSet 后要检查实际保留策略；PV 是否删除还取决于回收策略。不要把删除 Pod、删除 PVC 和清理存储数据混为一谈。

参考：StatefulSets。

7. DaemonSet：节点级常驻任务

典型用途是日志代理、节点监控、CNI/CSI 节点组件。目标是在每个符合条件的节点放一个 Pod，不设置 replicas；更新期间可因更新策略存在临时变化。

apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: node-demo
  namespace: k8s-notes
spec:
  selector:
    matchLabels:
      app: node-demo
  updateStrategy:
    type: RollingUpdate
    rollingUpdate:
      maxUnavailable: 1
  template:
    metadata:
      labels:
        app: node-demo
    spec:
      automountServiceAccountToken: false
      nodeSelector:
        kubernetes.io/os: linux
      containers:
        - name: demo
          image: busybox:1.36
          command: ["sh", "-c", "while true; do date; sleep 30; done"]
          resources:
            requests:
              cpu: 10m
              memory: 16Mi
            limits:
              cpu: 100m
              memory: 32Mi

这只是调度演示，不具备日志采集能力。控制平面节点常有污点，上例不会自动容忍所有控制平面污点。

kubectl get ds node-demo -n k8s-notes
kubectl get pods -n k8s-notes -l app=node-demo -o wide
kubectl describe ds node-demo -n k8s-notes

重点看 DESIRED、CURRENT、READY、AVAILABLE 是否符合预期节点范围。参考：DaemonSet。

8. Job 与 CronJob

8.1 Job：执行到成功完成

apiVersion: batch/v1
kind: Job
metadata:
  name: batch-demo
  namespace: k8s-notes
spec:
  completions: 3
  parallelism: 2
  backoffLimit: 2
  activeDeadlineSeconds: 120
  ttlSecondsAfterFinished: 3600
  template:
    spec:
      automountServiceAccountToken: false
      restartPolicy: Never
      containers:
        - name: worker
          image: busybox:1.36
          command: ["sh", "-c", "echo task-start; sleep 5; echo task-done"]

这里执行同一个命令直至累计 3 次成功，最多并行 2 个。业务分片需要 Indexed Job、队列或应用自行分工。任务可能因重试等原因重复执行，应设计幂等性。

Never 时失败容器不在原 Pod 内重启，Job 可创建新 Pod；OnFailure 时容器可在原 Pod 内重启，因此排障还要看 restartCount。

kubectl get jobs,pods -n k8s-notes
kubectl logs -n k8s-notes -l job-name=batch-demo --all-containers=true --prefix=true
kubectl wait --for=condition=complete job/batch-demo -n k8s-notes --timeout=150s

参考：Jobs。

8.2 CronJob：按计划创建 Job

apiVersion: batch/v1
kind: CronJob
metadata:
  name: scheduled-demo
  namespace: k8s-notes
spec:
  schedule: "*/5 * * * *"
  timeZone: Asia/Shanghai
  concurrencyPolicy: Forbid
  startingDeadlineSeconds: 120
  successfulJobsHistoryLimit: 2
  failedJobsHistoryLimit: 3
  suspend: false
  jobTemplate:
    spec:
      backoffLimit: 1
      activeDeadlineSeconds: 180
      template:
        spec:
          automountServiceAccountToken: false
          restartPolicy: Never
          containers:
            - name: task
              image: busybox:1.36
              command: ["sh", "-c", "date; echo scheduled-task"]

Forbid 表示上次未结束时跳过本次并发启动，不是保证排队补跑。CronJob 不提供严格 exactly-once 执行语义，扣款、发消息、备份等需业务幂等。修改 jobTemplate 不会改写已经创建的 Job。

参考：CronJob。

9. HPA：水平自动扩缩容

HPA 改的是目标资源副本数，不是单个容器的 CPU/内存配额，也不会自动增加节点。常见前提是 Metrics Server/资源指标 API 正常；自定义指标需要对应 adapter。

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: web
  namespace: k8s-notes
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: web
  minReplicas: 2
  maxReplicas: 6
  metrics:
    - type: Resource
      resource:
        name: cpu
        target:
          type: Utilization
          averageUtilization: 60
  behavior:
    scaleDown:
      stabilizationWindowSeconds: 300

若单个容器 CPU request 为 100m，使用 60m 就是其 request 的 60%，不是节点总 CPU 的 60%。存在多个容器时要考虑全部相关容器的 requests 和使用量。

近似理解：期望副本 ≈ ceil(当前副本 × 当前指标 / 目标指标)；实际还受容差、指标缺失、未就绪实例、扩缩速率和上下限影响。

kubectl top pods -n k8s-notes
kubectl get hpa web -n k8s-notes
kubectl describe hpa web -n k8s-notes
kubectl get apiservice v1beta1.metrics.k8s.io

<unknown> 先检查指标服务、资源 requests 和事件。HPA 与反复 apply 固定 replicas 可能相互覆盖；采用 HPA 后应在发布管理中明确副本字段所有权。扩容后 Pod Pending，还要检查节点容量和调度约束。

参考：Horizontal Pod Autoscaling。

10. PV、PVC 与 StorageClass

先记关系：应用在同命名空间引用 PVC；PVC 绑定集群级 PV；PV 描述实际存储。StorageClass 让 provisioner 根据 PVC 动态创建存储和 PV。

10.1 常用字段

10.2 静态 NFS 案例：PV + PVC + 消费 Pod

这是有环境依赖的模板：把 192.0.2.10 替换为可达 NFS 地址，把路径替换为真实导出。需已配置 NFS 服务、节点挂载依赖、网络和目录权限；声明 PV 不会创建 NFS 服务。

apiVersion: v1
kind: PersistentVolume
metadata:
  name: lab-nfs-pv
spec:
  capacity:
    storage: 5Gi
  accessModes: [ReadWriteMany]
  volumeMode: Filesystem
  persistentVolumeReclaimPolicy: Retain
  storageClassName: ""
  nfs:
    server: 192.0.2.10
    path: /exports/k8s-notes
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: shared-data
  namespace: k8s-notes
spec:
  accessModes: [ReadWriteMany]
  volumeMode: Filesystem
  storageClassName: ""
  volumeName: lab-nfs-pv
  resources:
    requests:
      storage: 5Gi
---
apiVersion: v1
kind: Pod
metadata:
  name: storage-demo
  namespace: k8s-notes
spec:
  automountServiceAccountToken: false
  containers:
    - name: reader
      image: busybox:1.36
      command: ["sh", "-c", "ls -la /data; sleep 3600"]
      volumeMounts:
        - name: data
          mountPath: /data
  volumes:
    - name: data
      persistentVolumeClaim:
        claimName: shared-data

NFS 示例中的 5Gi 通常是 Kubernetes 绑定依据，不保证服务端目录自动有 5Gi 硬配额。一个 PV 通常与一个 PVC 一对一绑定，多个 Pod 通过同一个 PVC 共享。

10.3 动态 PVC 案例

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: dynamic-data
  namespace: k8s-notes
spec:
  storageClassName: lab-storage
  accessModes: [ReadWriteOnce]
  resources:
    requests:
      storage: 5Gi

前提：替换存储类名并确认 provisioner 正常。WaitForFirstConsumer 下，PVC 在没有消费 Pod 前 Pending 可能正常。扩容通常增加 PVC 请求容量，不能通过缩小请求实现缩容；是否在线完成取决于驱动。

kubectl get sc
kubectl get pvc -n k8s-notes
kubectl get pv
kubectl describe pvc dynamic-data -n k8s-notes
kubectl describe pod storage-demo -n k8s-notes

排查分三层：PVC 是否 Bound → 卷是否 Attach/Mount 成功 → 应用 UID/GID、权限与读写是否正常。Bound 不等于挂载成功，挂载成功也不等于数据和业务正常。Retain 后的 Released PV 需要人工确认数据归属和回收流程，不能直接当空盘复用。

参考：Persistent Volumes、Storage。

11. Service、DNS 与 EndpointSlice

11.1 字段与端口关系

apiVersion: v1
kind: Service
metadata:
  name: web
  namespace: k8s-notes
spec:
  type: ClusterIP
  selector:
    app: web
  ports:
    - name: http
      port: 80
      targetPort: http

这里客户端请求 Service 的 80 端口，转到 Pod 名为 http 的端口，即前文 nginx 的 80。containerPort 只是声明信息，最终必须有进程实际监听。

默认集群域下可访问 web.k8s-notes.svc.cluster.local；同命名空间通常用 web 即可。集群域可能被定制。

kubectl get svc web -n k8s-notes
kubectl get endpointslices -n k8s-notes -l kubernetes.io/service-name=web -o yaml
kubectl get pods -n k8s-notes -l app=web --show-labels
# toolbox 镜像包含 wget/nslookup 时可直接验证
kubectl exec -n k8s-notes toolbox -- nslookup web.k8s-notes.svc.cluster.local
kubectl exec -n k8s-notes toolbox -- wget -qO- http://web

Service 存在但后端为空：优先检查 selector、Pod 标签、Ready 条件。跨节点失败再看 CNI、Service 数据面、NetworkPolicy 和节点网络。

参考：Service。

12. Ingress 与 Gateway API

Ingress 主要表达 HTTP/HTTPS 的 host/path 路由。需要实际安装的 Ingress Controller 和匹配的 IngressClass；仅创建 Ingress 对象不会凭空出现入口代理。

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: web
  namespace: k8s-notes
spec:
  ingressClassName: lab-ingress
  rules:
    - host: web.example.test
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: web
                port:
                  number: 80

Prefix 按路径段匹配，不是任意字符串前缀。rewrite、超时等 annotation 依控制器而异，不能跨实现照搬。

Ingress API 已冻结但仍可用。Gateway API 值得补充学习：GatewayClass 定义实现，Gateway 表达入口，HTTPRoute 等表达路由；通常需要额外 CRD 与控制器，不属于安装 Kubernetes 就一定具备的核心内置资源。

参考：Ingress。

13. ConfigMap 与 Secret

apiVersion: v1
kind: ConfigMap
metadata:
  name: app-config
  namespace: k8s-notes
data:
  APP_MODE: "learning"
  app.conf: |
    log_level=info
    timeout=5
---
apiVersion: v1
kind: Secret
metadata:
  name: app-secret
  namespace: k8s-notes
type: Opaque
stringData:
  API_TOKEN: "EXAMPLE_ONLY_REPLACE_ME"

下面是 Pod 或 Deployment 的 PodSpec 下配置片段，不能单独 apply：

containers:
  - name: app
    image: busybox:1.36
    command: ["sh", "-c", "sleep 3600"]
    env:
      - name: APP_MODE
        valueFrom:
          configMapKeyRef:
            name: app-config
            key: APP_MODE
      - name: API_TOKEN
        valueFrom:
          secretKeyRef:
            name: app-secret
            key: API_TOKEN
    volumeMounts:
      - name: config
        mountPath: /etc/app
        readOnly: true
volumes:
  - name: config
    configMap:
      name: app-config
      items:
        - key: app.conf
          path: app.conf

环境变量注入的值不会随配置修改自动刷新，需要重建容器。普通卷投射可最终更新，应用仍要支持重新读取；subPath 挂载不接收这类自动更新。

真实 Secret 不应直接写入公开 Git、报告或聊天；需要最小 RBAC、存储加密与合适的密钥管理。能读 Secret 或能在相应权限范围创建 Pod，可能获得敏感数据，不能只看名称是否“隐藏”。

参考：ConfigMaps、Secret 使用建议。

14. 必须补充的运行与治理知识

14.1 标签、选择器与所有权：资源关联的基础

Deployment.spec.selector.matchLabels.app = web
Deployment.spec.template.metadata.labels.app = web
Service.spec.selector.app = web

三者值应一致，但含义不同：控制器 selector 判定管理对象；模板 labels 标记 Pod；Service selector 判定流量后端。一个 Namespace 中不同控制器要避免使用重叠 selector。

kubectl get pod -n k8s-notes --show-labels
kubectl get pod -n k8s-notes -l app=web
kubectl get pod -n k8s-notes -l app=web -o jsonpath='{range .items[*]}{.metadata.name}{" => "}{.metadata.ownerReferences[*].kind}{"/"}{.metadata.ownerReferences[*].name}{"\n"}{end}'

14.2 调度：nodeSelector、亲和性、污点与拓扑分散

PodSpec 片段，需要节点具有 workload=general 标签；如节点另有污点，还要满足其他限制：

nodeSelector:
  workload: general
tolerations:
  - key: dedicated
    operator: Equal
    value: learning
    effect: NoSchedule
topologySpreadConstraints:
  - maxSkew: 1
    topologyKey: kubernetes.io/hostname
    whenUnsatisfiable: ScheduleAnyway
    labelSelector:
      matchLabels:
        app: web

NoSchedule 主要阻止新调度；PreferNoSchedule 为偏好性限制；NoExecute 还可能驱逐不能容忍的现有 Pod。调度可用性要同时满足资源、标签、污点、拓扑和卷约束。

kubectl get nodes -o wide
kubectl get nodes --show-labels
kubectl describe node NODE_NAME
kubectl describe pod POD_NAME -n k8s-notes

参考：Assigning Pods to Nodes。

14.3 ServiceAccount 与 RBAC：身份、权限和绑定

ServiceAccount 是“谁”，Role 是“可以做什么”，RoleBinding 是“把权限授给谁”。ClusterRole 可以通过 RoleBinding 限定在某命名空间使用，ClusterRoleBinding 则是集群范围绑定。

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

Pod 通过 spec.serviceAccountName: pod-reader 使用该身份。普通应用不访问 Kubernetes API 时，可设置 automountServiceAccountToken: false。新式令牌通常通过投射卷获取，不应假设创建 ServiceAccount 后自动生成长期 Secret token。

# 执行者需有相应 impersonate 权限，否则该检查可能被拒绝
kubectl auth can-i list pods -n k8s-notes --as=system:serviceaccount:k8s-notes:pod-reader
kubectl auth can-i delete pods -n k8s-notes --as=system:serviceaccount:k8s-notes:pod-reader

参考：RBAC。

14.4 NetworkPolicy：网络流量访问规则

前提：网络插件实际支持并实施 NetworkPolicy。未被策略隔离的 Pod，在对应方向通常默认允许；多个匹配策略的允许规则相加。目的 Pod 入站和源 Pod 出站都需要允许。

下面仅允许同命名空间 app=toolbox 的 Pod 访问 app=web 的 TCP 80，其他入站将受到限制；没有限制 web 的出站。这会影响前面 Ingress 的访问，不要在贯通基础实验中直接混用。

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: web-ingress
  namespace: k8s-notes
spec:
  podSelector:
    matchLabels:
      app: web
  policyTypes: [Ingress]
  ingress:
    - from:
        - podSelector:
            matchLabels:
              app: toolbox
      ports:
        - protocol: TCP
          port: 80

顶层 podSelector 选被保护的 Pod，规则内 from 选允许的来源。podSelector: {} 在顶层表示选中本命名空间全部 Pod。

同一条 peer 内同时出现 namespaceSelector 与 podSelector 是 AND；列表中的两条独立 peer 是 OR。限制 Egress 时要考虑 DNS UDP/TCP 53、依赖服务和外部系统。仅资源创建成功不能证明策略已生效，应验证允许与拒绝两种流量。

参考：Network Policies。

14.5 ResourceQuota 与 LimitRange：总量和单体约束

apiVersion: v1
kind: ResourceQuota
metadata:
  name: learning-quota
  namespace: k8s-notes
spec:
  hard:
    requests.cpu: "4"
    requests.memory: 8Gi
    limits.cpu: "8"
    limits.memory: 16Gi
    pods: "30"
    requests.storage: 50Gi
---
apiVersion: v1
kind: LimitRange
metadata:
  name: container-defaults
  namespace: k8s-notes
spec:
  limits:
    - type: Container
      defaultRequest:
        cpu: 100m
        memory: 64Mi
      default:
        cpu: 500m
        memory: 256Mi

Quota 控制命名空间资源总量；LimitRange 可设置每容器/Pod/PVC 的默认值和上下限，上例只演示容器默认值。它们不增加节点容量。设置 CPU/内存配额后，缺少必要 request/limit 且未被默认补齐的 Pod 可能被拒绝；Deployment 本身成功，但创建 Pod 可能在 ReplicaSet 事件里报错。

这些属于治理扩展实验，先评估所有示例的累计需求再启用。

参考：Resource Quotas。

14.6 PodDisruptionBudget：节点维护时保留服务能力

apiVersion: policy/v1
kind: PodDisruptionBudget
metadata:
  name: web
  namespace: k8s-notes
spec:
  minAvailable: 1
  selector:
    matchLabels:
      app: web

minAvailable 与 maxUnavailable 二选一。PDB 主要约束通过 Eviction API 的自愿中断，例如正常 drain；不防机器突然宕机，也不直接限制 Deployment 自身滚动更新。直接删除 Pod 也不能指望 PDB 拦截。

kubectl get pdb web -n k8s-notes
kubectl describe pdb web -n k8s-notes

ALLOWED DISRUPTIONS 为 0 时，维护驱逐可能被阻塞，需要先确认副本健康、容量和预算。参考：Disruptions。

14.7 securityContext 与优雅退出

适合支持非 root 运行的镜像的容器安全片段，不能不经验证直接套到依赖 root/写系统目录的镜像：

securityContext:
  runAsNonRoot: true
  runAsUser: 10001
  allowPrivilegeEscalation: false
  readOnlyRootFilesystem: true
  capabilities:
    drop: [ALL]
  seccompProfile:
    type: RuntimeDefault

这是容器级片段，写在 containers[] 下；fsGroup 等则放在 Pod 级 spec.securityContext。只读根文件系统下，应用缓存、临时目录可能需要独立可写卷。还应了解 Namespace 的 Pod Security Admission 标签，它会按策略拒绝不合规 Pod。

优雅退出需要应用正确处理 SIGTERM、停止接新请求并完成在途工作。preStop 执行会消耗退出宽限期，超时可能被强制终止；加一个 sleep 不等于已实现可靠排空。

14.8 运维必须理解的组件和扩展

15. 贯通实验与验收

15.1 最小实验：Namespace → Deployment → Service → 请求成功

将第 3 节 Namespace、第 5 节完整 Deployment、第 11 节 Service 按顺序保存为 01-namespace.yaml、02-web.yaml、03-service.yaml。本节文件名指你自己保存的实验文件，笔记未自动拆分生成它们。

# 只读：确认目标
kubectl config current-context
kubectl get nodes

# 服务端 dry-run 会经过校验/准入，但不持久化这些资源
kubectl apply --dry-run=server -f 01-namespace.yaml
# 创建 Namespace 后，才能针对它校验后续命名空间资源
kubectl apply -f 01-namespace.yaml
kubectl apply --dry-run=server -f 02-web.yaml
kubectl apply --dry-run=server -f 03-service.yaml

# 实际部署变更
kubectl apply -f 02-web.yaml
kubectl apply -f 03-service.yaml
kubectl rollout status deployment/web -n k8s-notes --timeout=180s
kubectl get deploy,rs,pods,svc -n k8s-notes
kubectl get endpointslices -n k8s-notes -l kubernetes.io/service-name=web

# 临时打开本地访问隧道，终端保持运行
kubectl port-forward -n k8s-notes svc/web 8080:80

在另一个终端执行：

curl --fail --show-error http://127.0.0.1:8080/

这证明通过本地隧道能访问被选中的 Pod；port-forward 不完整覆盖 ClusterIP 数据面、集群 DNS、Ingress、外部 LB。继续部署第 4 节 toolbox，从 Pod 内 wget http://web 与 nslookup 才能补充验证集群内访问。

15.2 扩展实验顺序

1. Job：观察 Active → Complete，并查看日志。
2. CronJob：观察它新建 Job；验证时区、并发策略与历史保留。
3. HPA：确认指标 API 后添加，观察真实 CPU 指标与副本变化；静态网页低负载未必会扩容。
4. StatefulSet：先配置可用 StorageClass，检查每 Pod 独立 PVC、稳定身份与数据保留。
5. Ingress：先确认控制器与 IngressClass，再验证入口地址、Host 路由和 Service。
6. NetworkPolicy：在隔离实验环境验证允许和拒绝来源，避免误阻入口流量。
7. RBAC、Quota、PDB：逐个添加，观察准入、权限和维护行为。

15.3 验收看什么

实验清理应只针对自己创建的对象。删除 Namespace 会删除其中工作负载和 PVC，可能按 PV 回收策略触发实际存储删除；先确认数据再清理。本文不执行任何清理。

16. 故障定位速查

16.1 通用顺序

kubectl get pods -n k8s-notes -o wide
kubectl describe pod POD_NAME -n k8s-notes
kubectl logs POD_NAME -n k8s-notes -c CONTAINER_NAME --tail=200
kubectl logs POD_NAME -n k8s-notes -c CONTAINER_NAME --previous --tail=200
kubectl get events -n k8s-notes --sort-by=.metadata.creationTimestamp
kubectl get deploy,sts,ds,job,cronjob,hpa -n k8s-notes
kubectl get svc,pvc -n k8s-notes
kubectl get nodes

--previous 读取同 Pod 中该容器上一次实例的日志；Pod 已删除或日志已回收后不一定还能拿到。Events 保留时间有限，长期追踪需要日志和监控系统。kubectl get all 不包括所有种类，例如不能替代对 PVC、Secret、Ingress、策略的单独检查。

16.2 状态与症状

Pod phase 只有 Pending、Running、Succeeded、Failed、Unknown 等；kubectl get pods 的 STATUS 列也可能显示容器等待或终止原因。不要把 CrashLoopBackOff 当成 Pod phase。

16.3 高频错误记忆表

17. 学习顺序与官方资料

建议先熟悉：公共字段、标签 → Namespace、Pod → Deployment、Service、DNS → 配置、探针、资源 → Job/CronJob、DaemonSet → PVC/PV/StorageClass、StatefulSet → 调度、HPA → Ingress、RBAC、NetworkPolicy、Quota、PDB。

每学一种资源，回答五个问题：它解决什么问题？谁创建并管理它？关键 spec 在哪里？依赖什么组件？怎样用实际结果验收？

官方资料索引

• Kubernetes API 与字段参考
• 工作负载概览
• Namespaces
• Deployments
• StatefulSets
• DaemonSet
• Jobs
• CronJob
• Horizontal Pod Autoscaling
• Persistent Volumes
• Service
• Ingress
• ConfigMaps
• Secret 使用建议
• 容器资源管理
• 探针配置
• Pod 调度
• RBAC
• NetworkPolicy
• ResourceQuota
• Pod Disruptions 与 PDB

文档核对与实测边界：参考链接已检索核对；本文示例按教学场景编写。静态格式检查不能替代目标 Kubernetes API 的服务端校验、组件兼容性检查和真实业务验收。官方滚动文档可能包含比你的集群更新的字段，使用时请选择目标版本文档。