{
  "id": "kubernetes/pvc-stuck-pending-no-storage-class",
  "signature": "persistentvolumeclaim is stuck in Pending state",
  "signature_zh": "persistentvolumeclaim 卡在 Pending 状态",
  "regex": "persistentvolumeclaim is stuck in Pending state",
  "domain": "kubernetes",
  "category": "resource_error",
  "subcategory": null,
  "root_cause": "The PersistentVolumeClaim cannot bind because the requested storage class does not exist, the provisioner is not deployed, or no matching PersistentVolume is available.",
  "root_cause_type": "generic",
  "root_cause_zh": "PersistentVolumeClaim 无法绑定，因为请求的存储类不存在、Provisioner 未部署或没有可用的匹配 PersistentVolume。",
  "versions": [
    {
      "version": "Kubernetes 1.28.x",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "Kubernetes 1.29.x",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    },
    {
      "version": "CSI drivers v1.30.x",
      "introduced": null,
      "deprecated": null,
      "removed": null,
      "behavior_change": null,
      "status": "active"
    }
  ],
  "os_specific": {},
  "dead_ends": [
    {
      "action": "Delete and recreate the PVC with the same spec.",
      "why_fails": "Recreating the same PVC without fixing the storage class or provisioner will result in the same Pending state.",
      "fail_rate": 0.85,
      "condition": "",
      "sources": []
    },
    {
      "action": "Manually create a PersistentVolume without matching the PVC's storage class or size.",
      "why_fails": "A manually created PV must match the PVC's storage class, access modes, and size (or be larger) to bind. Mismatched PVs will remain unbound.",
      "fail_rate": 0.7,
      "condition": "",
      "sources": []
    },
    {
      "action": "Set storageClassName to empty string to use default class without verifying existence.",
      "why_fails": "If no default StorageClass exists, the PVC will still be Pending. Use `kubectl get storageclass` to verify.",
      "fail_rate": 0.6,
      "condition": "",
      "sources": []
    }
  ],
  "workarounds": [
    {
      "action": "Check StorageClass existence: `kubectl get storageclass`. If the requested class (e.g., 'fast') is missing, create it: `kubectl apply -f - <<EOF\napiVersion: storage.k8s.io/v1\nkind: StorageClass\nmetadata:\n  name: fast\nprovisioner: kubernetes.io/aws-ebs\nparameters:\n  type: gp3\nEOF`",
      "success_rate": 0.85,
      "how": "Check StorageClass existence: `kubectl get storageclass`. If the requested class (e.g., 'fast') is missing, create it: `kubectl apply -f - <<EOF\napiVersion: storage.k8s.io/v1\nkind: StorageClass\nmetadata:\n  name: fast\nprovisioner: kubernetes.io/aws-ebs\nparameters:\n  type: gp3\nEOF`",
      "condition": "",
      "sources": []
    },
    {
      "action": "If using a CSI driver, verify the driver is deployed: `kubectl get csidrivers`. If missing, install the driver (e.g., EBS CSI driver: `kubectl apply -k \"github.com/kubernetes-sigs/aws-ebs-csi-driver/deploy/kubernetes/overlays/stable/?ref=master\"`).",
      "success_rate": 0.8,
      "how": "If using a CSI driver, verify the driver is deployed: `kubectl get csidrivers`. If missing, install the driver (e.g., EBS CSI driver: `kubectl apply -k \"github.com/kubernetes-sigs/aws-ebs-csi-driver/deploy/kubernetes/overlays/stable/?ref=master\"`).",
      "condition": "",
      "sources": []
    },
    {
      "action": "Describe the PVC for detailed events: `kubectl describe pvc <pvc-name> -n <namespace>`. Look for 'waiting for first consumer to be created before binding' which indicates dynamic provisioning is waiting for a pod. If so, create a pod that uses the PVC.",
      "success_rate": 0.9,
      "how": "Describe the PVC for detailed events: `kubectl describe pvc <pvc-name> -n <namespace>`. Look for 'waiting for first consumer to be created before binding' which indicates dynamic provisioning is waiting for a pod. If so, create a pod that uses the PVC.",
      "condition": "",
      "sources": []
    }
  ],
  "workarounds_zh": [
    "检查 StorageClass 是否存在：`kubectl get storageclass`。如果请求的类（例如 'fast'）缺失，创建它：`kubectl apply -f - <<EOF\napiVersion: storage.k8s.io/v1\nkind: StorageClass\nmetadata:\n  name: fast\nprovisioner: kubernetes.io/aws-ebs\nparameters:\n  type: gp3\nEOF`",
    "如果使用 CSI 驱动，验证驱动是否部署：`kubectl get csidrivers`。如果缺失，安装驱动（例如 EBS CSI 驱动：`kubectl apply -k \"github.com/kubernetes-sigs/aws-ebs-csi-driver/deploy/kubernetes/overlays/stable/?ref=master\"`）。",
    "描述 PVC 以获取详细事件：`kubectl describe pvc <PVC名称> -n <命名空间>`。查找 'waiting for first consumer to be created before binding'，这表示动态配置正在等待 Pod。如果是，创建一个使用该 PVC 的 Pod。"
  ],
  "transition_graph": {
    "leads_to": [],
    "preceded_by": [],
    "frequently_confused_with": []
  },
  "official_doc_url": "https://kubernetes.io/docs/concepts/storage/persistent-volumes/#persistentvolumeclaims",
  "official_doc_section": null,
  "error_code": null,
  "verification_tier": "ai_generated",
  "confidence": 0.87,
  "fix_success_rate": 0.82,
  "resolvable": "true",
  "first_seen": "2023-03-01",
  "last_confirmed": "2024-06-01",
  "last_updated": "2024-06-01",
  "evidence_count": 1,
  "tags": [],
  "locale": "en",
  "aliases": []
}