PV / PVC / StorageClass / CSI 深入

graph TB
    subgraph 应用[应用层]
        Pod["Pod<br>volumes:<br>  persistentVolumeClaim:<br>    claimName: my-pvc"]
    end

    subgraph 用户[用户层]
        PVC["PersistentVolumeClaim<br>(申请: 我要 10Gi RWO)"]
    end

    subgraph 管理员[集群管理员层]
        PV["PersistentVolume<br>(实际存储资源)"]
        SC["StorageClass<br>(自动创建 PV 的模板)"]
    end

    subgraph 底层[实际存储]
        Disk["云盘 / NFS / Ceph / Local"]
    end

    Pod --> PVC
    PVC -.绑定.-> PV
    PVC -.或: 通过.-> SC
    SC -.动态创建.-> PV
    PV --> Disk

    style 应用 fill:#e1f5ff
    style 用户 fill:#ffe1f5
    style 管理员 fill:#fff4e1
    style 底层 fill:#e1ffe1

sequenceDiagram
    autonumber
    participant U as 用户
    participant PVC as PersistentVolumeClaim
    participant PVCtl as PV Controller
    participant SC as StorageClass
    participant CSI as CSI driver
    participant Cloud as 云厂商 API
    participant PV as PersistentVolume

    U->>PVC: kubectl apply pvc.yaml
    Note over PVC: status: Pending
    PVCtl->>PVC: 检测到新 PVC
    PVCtl->>SC: 查 StorageClass
    SC-->>PVCtl: provisioner: ebs.csi.aws.com
    PVCtl->>CSI: CreateVolume 调用
    CSI->>Cloud: 创建 EBS 卷
    Cloud-->>CSI: vol-abc123
    CSI->>PV: 创建 PV
    Note over PV: 包装 vol-abc123
    PVCtl->>PVC: bind PV
    Note over PVC: status: Bound<br>volumeName: pv-xxx

graph LR
    subgraph Immediate模式问题
        I1[PVC 创建] --> I2[CSI 立刻在 AZ-A 创建云盘]
        I2 --> I3[pod 调度到 AZ-B]
        I3 --> I4[云盘在 A、pod 在 B → 挂不上]
    end

    subgraph WaitForFirstConsumer
        W1[PVC 创建] --> W2[等]
        W2 --> W3[pod 调度到 AZ-B]
        W3 --> W4[CSI 在 AZ-B 创建云盘]
        W4 --> W5[成功挂]
    end

    style I4 fill:#ffe1e1
    style W5 fill:#e1ffe1

graph TB
    subgraph CtrlPlane[控制面节点]
        Provisioner["csi-provisioner<br>(Deployment)<br>处理 PVC 创建"]
        Attacher["csi-attacher<br>(Deployment)<br>处理 VolumeAttachment"]
        ResizeC["csi-resizer<br>(Deployment)<br>处理扩容"]
        Snap["csi-snapshotter<br>(Deployment)<br>处理 VolumeSnapshot"]
    end

    subgraph EachNode[每个节点]
        NodeReg["csi-node-driver-registrar<br>(DaemonSet)<br>向 kubelet 注册"]
        NodePlugin["csi-driver<br>(实际 mount 操作)"]
    end

    subgraph K8sAPI[K8s API]
        PVC
        PV
        VA["VolumeAttachment<br>(K8s 内部资源)"]
    end

    PVC --> Provisioner
    Provisioner --> PV
    PV --> Attacher
    Attacher --> VA
    VA --> NodePlugin
    NodePlugin -.mount.-> Disk["实际磁盘"]

    style CtrlPlane fill:#e1f5ff
    style EachNode fill:#ffe1f5

sequenceDiagram
    autonumber
    participant K8s as K8s API
    participant Sched as Scheduler
    participant Prov as csi-provisioner
    participant Att as csi-attacher
    participant Kubelet
    participant Node as csi-node
    participant Cloud as 云盘 API

    K8s->>Prov: PVC 创建
    Prov->>Cloud: CreateVolume
    Cloud-->>Prov: vol-id
    Prov->>K8s: 创建 PV、bind PVC

    K8s->>Sched: 调度 pod
    Sched->>K8s: pod 分配到 m4

    K8s->>Att: 创建 VolumeAttachment(m4, pv)
    Att->>Cloud: AttachVolume(vol-id, m4)
    Cloud-->>Att: /dev/sdb attached to m4

    Kubelet->>Node: NodeStageVolume(pv, /var/lib/kubelet/.../staging)
    Note over Node: mkfs (首次) + mount 到 staging 目录
    Kubelet->>Node: NodePublishVolume(pv, /var/lib/kubelet/pods/.../mount)
    Note over Node: bind mount staging → pod 目录
    Note over Kubelet: pod 启动、bind 给容器

flowchart TD
    Start[PVC Pending] --> S1{kubectl describe pvc<br>Events 说啥?}
    S1 -->|storageclass not found| F1[创建 SC]
    S1 -->|ProvisioningFailed| S2{看 CSI driver 日志}
    S2 -->|IAM/网络| F2[修云上凭证 / 网络]
    S2 -->|配额| F3[申请扩配额]
    S1 -->|waiting for first consumer| S3{Pod 是不是<br>真在等?}
    S3 -->|Pod 也 Pending| F4[调度问题 / taint / 资源不足]
    S3 -->|Pod Running| F5[底层 CSI 调用有问题]
    S1 -->|匹配 PV 失败| F6[手动创建 PV / 改 PVC accessMode]